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. Si vous ne suivez pas ces recommandations, nous n’accepterons pas votre document.

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

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.

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.

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