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. If you don’t follow these guidelines, we will not accept your document.

Titre

All pages must have a document title that will be shown in the table of contents (left sidebar) and at the top of the page.

Les mots dans les titres doivent commencer par une minuscule plutôt que par une majuscule. 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.

Page titles are underlined with equals signs. For example, the markup for Remonter un problème includes the following title:

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

Note that:

  1. The title is sentence cased
  2. The title is underlined with equals signs
  3. The underline spans the title completely without going over

Incorrect examples of titles include:

  • Incorrect casing

    Bug Reporting
    =============
    
  • Underline too short

    Bug reporting
    =====
    
  • Underline too long

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

Headings

There are several levels of headings that you may place on your page. These levels are shown here in order:

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

Level one
---------

Level two
^^^^^^^^^

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

Each heading level creates a sub-section in the global table of contents tree available when the documentation is built. In the primary (web) version of the documentation, this only shows four levels deep from the top level of the documentation. Please refrain from using more heading levels than will show in this tree as it makes navigating your document difficult. If you must use this many heading levels, it is a good sign that your document should be split up into multiple 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.

You can do this by adding the page to the index.rst file in the same directory that you created it. For example, if you create a file called « newpage.rst », you would add the line marked with a chevron (>) in the nearest index:

.. 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.

Avertissements

Your edits must not introduce any warnings into the documentation build. If any warnings occur, the build will fail and your pull request will be marked with a red “X”. Please ensure that your RST is valid and correct before you create a pull request. This is done automatically (via sphinx-build crashing with your error) if you follow our build instructions below.

Line length

There is no restriction on line length in this repository. Please do not break lines at an arbitrary line length. Instead, turn on word wrap in your text editor.

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.

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

This section lists the TODOs that have been included in this documentation. If you know how to fix one, please send us a Pull Request to make it better!

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

.. todo:

   My todo text

À faire

Changez le lien rootstock pour pointer vers UBports une fois que le PR actuallyfixit est fusionné.

(l'entrée originale se trouve dans /home/docs/checkouts/readthedocs.org/user_builds/docsubportscom-french/checkouts/latest/porting/installing-16-04.rst, à la ligne 28)