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

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

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 se relient à 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 expérience terrible que de suivre un lien depuis un autre site, d’atterrir sur une page 404 et d’être laissé à soi-même pour trouver son chemin dans une documentation restructurée.

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.

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

Contrôle final de votre contribution#

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

Faites défiler jusqu’au bas de l’onglet « Conversation » de votre demande de fusion sur Github. Vous verrez ici les vérifications (vous devrez peut-être cliquer sur « Afficher toutes les vérifications »)
Il se peut qu’un point jaune apparaisse, c’est-à-dire « en attente ». Dans ce cas, attendez quelques secondes de plus.
Ou bien il peut avoir une croix rouge, c’est-à-dire qu’elle a échoué. Dans ce cas, veuillez vérifier pourquoi elle a échoué
Si une case verte est cochée, cela signifie que la demande de fusion a pu être générée avec succès
Veuillez maintenant cliquer sur « Détails »,
puis « Artefacts » en haut à droite,
puis « _build/html/..index.html »,
et enfin sur « Aller à la page de démarrage ».

Vous pouvez maintenant parcourir une version complète du site de la documentation d’UBports avec votre contribution incluse. Vérifiez que vos modifications sont correctes.

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

There is also another way to create somewhat more featureful webapps, sometimes referred to as webapp+ or alternative container. This needst to be properly documented. It’s a simple qml app that can be easily configured. Creation is almost as simple as “classic” webapp, but result is more powerfull with the a nice navigation feature. A rather advanced example of this is the YouTube app from Mateo Salta which has quite some modifications on top of the template.

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

À 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 57)