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

These rules govern how you should write your documentation to avoid problems with style, format, or linking.

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.

Titles should be « sentence cased » rather than « Title Cased ». For example:

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 :

  1. La casse du titre est celle d’une phrase

  2. Le titre est souligné avec des signes égal

  3. 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 votre page. Ces niveaux sont présentés ci-dessous dans l’ordre :

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

Level one
---------

Level two
^^^^^^^^^

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

Chaque niveau de chapitre créé une sous-section dans l’arborescence du sommaire général disponible lorsque la documentation est construite. Dans la version principale de la documentation (Web), seuls quatre niveaux de profondeur sont affichés à partir du niveau supérieur de la documentation. Veuillez éviter d’utiliser plus de niveaux de chapitres que ce qui ne peut apparaître dans l’arborescence car cela rend plus difficile la navigation au sein de votre document. Si vous devez utiliser autant de niveaux de chapitres, c’est le signe que votre documentation devrait être séparée en plusieurs pages.

Sommaire

Les visiteurs ne peuvent pas accéder à votre nouvelle page s’ils ne peuvent pas la trouver. Sphinx non plus. C’est pour quoi vous devez ajouter de nouvelles pages au sommaire de Sphinx.

Vous pouvez faire cela 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.

Moving pages

Sometimes it becomes necessary to move a page from one place in the documentation to another. Generally this is to improve document flow: For example, it makes more sense for the page to come after a page you’ve just added in a different section.

However, people link to our documentation from many sources that we do not control. Blogs, websites, and other documentation sites can direct people here using links that they may never update. It is a terrible experience to follow a link from a different site and land on a 404 page, left to your own devices to find your way in restructured documentation.

We use a tool called Rediraffe to avoid this bad experience. Rediraffe creates redirect pages which can send a user from an old, invalid link to a new, useful link. Please create a redirect link when changing a page’s name or moving a page within the documentation’s directory structure. Redirect links are created by placing the filename of the old document and the filename of the new document, relative to the documentation’s root, in the redirects.txt file.

We use Rediraffe’s checkdiff builder to ensure that pages are not deleted from the documentation without a redirect in place. This builder is run as part of the build.sh script in the repository and as part of our automated build once you submit a Pull Request.

What follows are some examples of situations where you should create redirects.

You are moving systemdev/calendars.rst to appdev/calendars.rst. Add the following to the redirects.txt file:

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

You are moving appdev/clickable.rst into several pages in appdev/clickable/ to give significantly more information about the tool than there was previously. You have created an introduction page, appdev/clickable/introduction.rst. In this case, it would be a good idea to redirect the old page to the new introduction page. This can be done by adding the following to 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 vous aideront à apporter une contribution à cette documentation après avoir rédigé un document.

Note

Vous aurez besoin d’un compte GitHub pour réaliser ces étapes. Si vous n’en avez pas, cliquez ici pour lancer le processus de création d’un compte.

Clonage du répertoire

Vous pouvez effectuer des modifications plus poussées dans notre documentation en clonant ubports/docs.ubports.com sur GitHub. Si vous n’êtes pas certain sur la manière de procéder, consultez l’excellent guide de GitHub sur le clonage de projets.

Compilation de la documentation

Si vous souhaitez compiler cette documentation avant de proposer votre modification (ce que vous devriez faire), suivez ces instructions dans votre copie locale de votre clone du répertoire.

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 rencontrez des problèmes lors de la compilation de la documentation, la première chose à essayer est la suppression de l’environnement de compilation. Exécutez rm -r ~/ubportsdocsenv et essayez de le compiler de nouveau. En fonction du moment où vous avez utilisé pour la première fois le script de compilation, vous aurez besoin d’exécuter la commande rm avec sudo.

Final check of your contribution

After you have created your PR on github, the CI (continuous integration) system will make a test build of your contribution. Please double check whether this builds successfully and whether the result looks as you intended it to:

  • Scroll to the bottom of the « Conversation » tab of your PR on github, here you will see the checks (You may have to click on « Show all checks »)

  • It can have a yellow dot, i.e., « pending » then wait a few more seconds.

  • Or it may have a red X, i.e., it failed. In this case please check why it failed

  • If it shows a green check mark, it means the PR could be built successfully

  • Now please click on « Details »,

  • then « Artifacts » on the top right,

  • then « _build/html/..index.html »,

  • and finally on « Go to start page ».

Now you can browse a complete build of the UBports docs site with your contribution included. Double check whether your changes look ok.

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 dans ReStructuredText mais que vous n’êtes pas à l’aise avec Git ou GitHub, 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 pour l’améliorer !

Pour créer une chose à faire, ajoutez cet indicateur dans votre page

.. todo::

   My todo text

À faire

Document the process for Nexus 4 (mako)

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