Documentation¶

Astuce

La documentation sur ce site est écrite en ReStructuredText, ou RST en version courte. Veuillez consulter l”introduction à RST si vous n’êtes pas familier avec celui-ci.

Cette page vous guidera dans l’écriture d’une bonne documentation pour le projet UBports pouvant être mise en avant sur ce site.

Recommandations pour l’écriture de la documentation¶

Ces règles précisent comment vous devez écrire votre documentation pour éviter des problèmes de style, de format ou de liens.

Titre¶

Toutes les pages doivent avoir un titre de document qui sera affiché dans le sommaire (volet de gauche) et en haut de la page.

Les titres devraient être « Casse basée sur la phrase » plutôt que « Casse basée sur le titre ». Par exemple :

Incorrect casing:
    Writing A Good Bug Report
Correct casing:
    Writing a good bug report
Correct casing when proper nouns are involved:
    Installing Ubuntu Touch on your phone

Il n’existe pas de règle unique que tout le monde puisse suivre pour l’écriture des titres, mais mettre des minuscules est simple. Cela aide à conserver les majuscules de manière cohérente dans le sommaire.

Les titres des pages sont soulignés avec des signes égal. Par exemple, le balisage pour Remonter un problème comprend le titre suivant :

Bug reporting
=============

Notez que :

La casse du titre est celle d’une phrase
Le titre est souligné avec des signes égal
Le soulignement couvre complètement le titre sans le dépasser

Voici quelques exemples incorrects de titres :

Casse incorrecte
Bug Reporting =============
Soulignement trop court
Bug reporting =====
Soulignement trop long
Bug reporting ================

Rubriques¶

Il existe plusieurs niveaux de chapitres que vous pouvez utiliser dans une page. Ces niveaux sont présentés ci-dessous dans l’ordre :

Page title
==========

Level one
---------

Level two
^^^^^^^^^

Level three
"""""""""""

Veuillez vous abstenir d’utiliser plus de quatre niveaux. Si vous pensez avoir besoin de plus de niveaux, c’est un bon signe que le document devrait être divisé en plusieurs pages. En outre, la version web de la documentation ne montre que quatre niveaux dans sa table des matières.

Sommaire¶

Si vous ajoutez une nouvelle page, vous devez aussi l’ajouter au sommaire. Vous pouvez le faire en ajoutant la page dans le fichier index.rst dans le même répertoire de création. Par exemple, si vous créez un fichier appelé « newpage.rst », vous ajouterez la ligne précédée d’un chevron (>) dans l’index le plus proche :

.. toctree::
    :maxdepth: 1
    :name: example-toc

    oldpage
    anotheroldpage
>   newpage

L’ordre est important. Si vous souhaitez que votre page apparaisse à une certaine place dans le sommaire, placez-la là. Dans l’exemple précédent, la nouvelle page serait ajoutée à la fin de ce sommaire.

Déplacement des pages¶

Il est parfois nécessaire de déplacer une page d’un endroit à l’autre de la documentation. En général, cela permet d’améliorer la fluidité de la documentation. Par exemple, il est plus logique que la page vienne après une page que vous venez d’ajouter dans une autre section.

Cependant, les gens créent des liens à notre documentation à partir de nombreuses sources que nous ne contrôlons pas. Les blogs, sites internet et autres sites de documentation peuvent orienter les gens vers notre site en utilisant des liens qu’ils ne mettront jamais à jour. C’est une très mauvaise expérience de suivre un lien depuis un autre site et d’aboutir à une page erreur 404, et d’avoir à chercher manuellement dans notre documentation.

Nous utilisons un outil appelé Rediraffe pour éviter cette mauvaise expérience. Rediraffe crée des pages de redirection qui peuvent envoyer un/e utilisateur/trice d’un ancien lien non valide vers un nouveau lien utile. Veuillez créer un lien de redirection lorsque vous changez le nom d’une page ou lorsque vous déplacez une page dans la structure du répertoire de la documentation. Les liens de redirection sont créés en plaçant le nom de fichier de l’ancien document et le nom de fichier du nouveau document, par rapport à la racine de la documentation, dans le fichier redirects.txt.

Nous utilisons le générateur checkdiff de Rediraffe pour nous assurer que les pages ne sont pas supprimées de la documentation sans qu’une redirection ne soit mise en place. Ce générateur est exécuté dans le cadre du script build.sh du dépôt et dans le cadre de notre génération automatique lorsque vous soumettez une demande d’extraction (MR).

Voici quelques exemples de situations dans lesquelles vous devez créer des redirections.

Vous déplacez systemdev/calendars.rst vers appdev/calendars.rst. Ajoutez ce qui suit au fichier redirects.txt :

"systemdev/calendars.txt" "appdev/calendars.txt"

Vous déplacez appdev/clickable.rst dans plusieurs pages dans appdev/clickable/ pour donner beaucoup plus d’informations sur l’outil qu’il n’y en avait auparavant. Vous avez créé une page d’introduction, appdev/clickable/introduction.rst. Dans ce cas, ce serait une bonne idée de rediriger l’ancienne page vers la nouvelle page d’introduction. Cela peut être fait en ajoutant ce qui suit au fichier redirects.txt : :

"appdev/clickable.rst" "appdev/clickable/introduction.rst"

Avertissements¶

Vos modifications ne doivent pas introduire d’avertissements dans la documentation construite. Si un avertissement se produit, la compilation échouera et votre proposition sera marquée d’un « X » rouge. Assurez-vous que votre fichier RST est valide et correct avant de soumettre une proposition. Ceci est fait automatiquement (via le plantage de sphinx-build avec votre erreur) si vous suivez nos instructions de compilation ci-dessous.

Longueur de ligne¶

Il n’y a pas de restriction de longueur de ligne dans ce dépôt. Veuillez ne pas faire de renvoi à la ligne pour une longueur arbitraire de longueur de ligne. À la place, activez le retour à la ligne automatique dans votre éditeur de texte.

Circuit de contribution¶

Les étapes suivantes expliqueront comment apporter une contribution à cette documentation.

Note

Vous aurez besoin d’un compte GitLab pour réaliser ces étapes. Si vous n’en avez pas, cliquez gitlab.com pour en créer un.

Clonage du répertoire¶

Vous pouvez effectuer des modifications plus poussées à la documentation en clonant ubports/docs.ubports.com sur GitLab.

Compilation de la documentation¶

Pour compiler cette documentation, suivez ces instructions dans votre copie locale de votre clone du dépôt.

La documentation peut être compilée en exécutant ./build.sh à la racine de ce répertoire. Le script créera également un environnement virtuel de compilation dans ~/ubportsdocsenv s’il n’est pas déjà présent.

Si tout s’est bien passé, vous pourrez accéder au répertoire _build et ouvrir index.html pour visualiser la documentation d’UBports.

Si vous avez des problèmes pour compiler la doc, la première chose à essayer est de supprimer l’environnement de compilation. Exécutez rm -r ~/ubportsdocsenv et ré-essayez de compiler.

Contrôle final de votre contribution¶

Après avoir créé votre demande de fusion sur GitLab, le système d’intégration continue fera un test de votre contribution (un « pipeline »). Veuillez vérifier que cette génération est réussie et si le résultat est conforme à vos attentes :

en haut de l’onglet « Overview » de votre MR sur gitlab, vous verrez l’état du pipeline
s’il est dit « Checking pipeline status » ou « Pipeline running » alors s’il vous plaît attendez encore une minute.
s’il est affiché « Pipeline failed » avec un X rouge et une erreur s’est produite, s’il vous plaît cliquez sur le lien pour trouver les détails
s’il dit « Pipeline passed » avec une marque de contrôle verte, cela signifie que le MR pourrait être construit avec succès et vous pouvez continuer à regarder les résultats
cliquez maintenant sur le lien de ce pipeline
cliquez sur « build » job
cela vous amène à la fin du journal de construction, où vous verrez un message : « Build succeeded, browse the artifact here »
cliquez sur le lien à coté pour voir la version complète du site de documentation UBports avec vos modifications
Ré-vérifiez que vos changements semblent corrects

Méthodes alternatives pour contribuer¶

Traductions¶

Le contenu de ce document est disponible à la traduction au niveau de son projet sous le Weblate d’UBports.

Rédaction de documents dans un format autre que RST¶

Si vous souhaitez écrire des documents pour UBports mais que vous n’êtes pas à l’aise avec l’écriture en ReStructuredText, veuillez l’écrire sans formatage et l’afficher sur le Forum UBports dans la section appropriée (probablement Général). Quelqu’un pourra vous aider à réviser votre ébauche et à rédiger le texte restructuré requis.

Mal à l’aise avec Git¶

Si vous avez écrit un document complet en ReStructuredText mais que vous n’êtes pas à l’aise avec Git ou GitLab, veuillez le poster sur le Forum UBports dans la section appropriée (probablement Général). Quelqu’un pourra vous aider à réviser votre ébauche et à la soumettre à cette documentation.

Actuellement à faire¶

Cette page liste les choses à faire qui devraient être incluses dans cette documentation. Si vous savez comment en régler une, merci de nous envoyer une proposition de fusion (MR) pour l’améliorer !

Pour créer un “todo”, ajoutez ce “markup” à votre page :

.. todo::

   My todo text

À faire

Pensez également à rédiger un document sur le processus de traitement des demandes de fusion.

(l'entrée originale se trouve dans /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-fr/checkouts/latest/about/process/issue-tracking.rst, à la ligne 36)

À faire

Il y a aussi une autre façon de créer des applications Web un peu plus élaborées, parfois appelée webapp+ ou conteneur alternatif. Cela doit être dûment documenté. C’est une simple application qml qui peut être facilement configurée. La création est presque aussi simple que l’application Web “classique”, mais le résultat est plus puissant avec une bonne fonctionnalité de navigation. Un exemple assez avancé est l’application YouTube de Mateo Salta qui a des améliorations appréciables au modèle.

(l'entrée originale se trouve dans /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-fr/checkouts/latest/appdev/webapp/index.rst, à la ligne 19)

À faire

Documenter le processus pour Nexus 4 (mako)

(l'entrée originale se trouve dans /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-gitlab-fr/checkouts/latest/systemdev/kernel-hal.rst, à la ligne 57)

Hébergement ReadTheDocs¶

Le site réel est construit et hébergé pour nous par le projet Read The Docs. Notre configuration RTD contient un projet principal pour l’anglais et un projet supplémentaire pour chaque langue supportée ajoutée comme traductions au projet principal. Si vous êtes un mainteneur et que vous voulez ajouter une langue, créez d’abord un nouveau projet avec l’importation manuelle et définissez le langage de manière appropriée. Ensuite, ajouter ceci comme une traduction dans la page Admin du projet principal.