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. Ce titre est souligné avec des signes égal.

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.

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 votre version de la documentation. Si un avertissement se produit, la compilation échouera et votre proposition sera marquée d’un « X » rouge. Assurez-vous que votre 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.

Mise à jour des traductions

Vous devez mettre à jour les fichiers de traduction pour qu’ils correspondent à vos modifications avant de les valider. Pour ce faire, lancez update-translations.sh dans ce répertoire.

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.

Souvenez-vous de mettre à jour les traductions, puis validez vos modifications et soumettez votre contribution.

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 seront inclues 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