Guide de style de balisage

Cette page couvre les conventions d’écriture et l’usage de la syntaxe de balisage reStructuredText (RST).

Conventions

  • Indentation à trois espaces.

  • Les lignes devraient faire moins de 128 caractères de long.

  • Utilisez l’italique pour les noms de bouton/menu.

Autres conventions :

  • Éviter les caractères Unicode.

  • Éviter le texte lourdement enveloppé (c.-à-d que les phrases peuvent avoir leurs propres lignes).

En-têtes

################
 Document Part
################

****************
Document Chapter
****************

Document Section
================

Document Subsection
-------------------

Document Subsubsection
^^^^^^^^^^^^^^^^^^^^^^

Document Paragraph
""""""""""""""""""

Note

Parts ne devraient être utilisés que pour le contenu ou les pages d’index.

Note

Chaque fichier .rst devrait seulement avoir un entête de chapitre (*) par fichier.

Style de texte

Voir le survol de ReStructured Text pour plus d’information sur le style des divers éléments de la documentation et sur la manière d’ajouter des listes, tables, images et blocs de code. La référence Sphinx fournit plus de détails sur les constructs supplémentaires.

Quelques balises utiles pour le style de texte :

*italic*
**bold**
``literal``

Éléments de l’interface

  • :kbd:`LMB` – raccourcis clavier et souris.

  • *Mirror* – étiquettes de l’interface.

  • :menuselection:`3D View --> Add --> Mesh --> Monkey` – menus.

Exemples de code

il y a prise en charge du surlignage de syntaxe si le langage de programmation est fourni, et les numéros de ligne peuvent être affichés facultativement avec l’option :linenos: :

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Images

Les formes devraient être utilisées pour placer les images :

.. figure:: /images/editors_menu.png

   Image Caption.

Fichiers

Pas de majuscules, pas d’espaces.

Les fichiers ont des noms en caractères minuscules avec des caractères de soulignement entre les mots.

Triez utilement

Ordonnez le nommage avec des identifiants spécifiques à la fin.

Format

Utilisez .png pour les images qui ont des couleurs solides telles que les captures d’écran de l’interface Blender, et .jpg pour les images avec beaucoup de variances de couleurs, tels que les rendus et photos.

N’utilisez pas de fichiers .gif animés. Ils sont difficiles à maintenir, peuvent être gênants et sont habituellement de grande taille. Si une vidéo est nécessaire, utilisez YouTube ou Vimeo (voir Vidéos ci-dessous).

Emplacement

Placez l’image dans le dossier manual/images. N’utilisez pas d’autres sous-dossiers.

Nommage

Les fichiers image devraient être nommés comme suit : chapter_subsection_id.png, ex :

  • render_cycles_lighting_example_01.jpg
  • interface_intro_splash.jpg
  • interface_ui_panel.jpg

N’utilisez pas de caractères spéciaux ou d’espaces.

Guides d’utilisation

  • Évitez de spécifier la résolution de l’image ou son alignement, ainsi le thème peut gérer les images de façon cohérente et fournir la meilleure disposition pour un éventail de tailles d’écran différentes.

  • En documentant un panneau ou une section de l’UI, c’est mieux d’utiliser une seule image qui montre tous les zones pertinentes (plutôt que de multiples images pour chaque icône ou bouton) placé en haut de la section que vous êtes en train d’écrire, et ensuite expliquez les fonctionnalités dans l’ordre de leur apparition dans l’image.

    Note

    Il est important que le manuel puisse être maintenu au long terme. Comme l’UI et les options des outils changent, essayez d’éviter d’avoir beaucoup d’images (quand elles ne sont pas spécialement nécessaires). Autrement, ceci devient une charge en maintenance beaucoup trop lourde.

Vidéos

Les vidéos sur Youtube et Vimeo peuvent être incrustées en utilisant

.. youtube:: ID

.. vimeo:: ID

L’ID se trouve dans l’URL de la vidéo, ex. :

  • L’ID pour https://www.youtube.com/watch?v=Ge2Kwy5EGE0 est Ge2Kwy5EGE0

  • L’ID pour https://vimeo.com/15837189 est 15837189

Guides d’utilisation

  • Éviter d’ajouter des vidéos qui reposent sur la voix, étant donné que cela est difficile à traduire.

  • N’incrustez pas de tutoriels vidéos comme moyen pour expliquer une fonctionnalité, le texte lui-même devrait l’expliquer adéquatement (bien que vous puissiez ajouter un lien vers la vidéo en bas de la page sous l’en-tête Tutorials).

Constructs utiles

  • |BLENDER_VERSION| – Résout la version de Blender courante.

  • :abbr:`SSAO (Screen Space Ambient Occlusion)` – Les abréviations affichent le texte entier comme infobulle pour le lecteur.

  • :term:`Manifold` – Crée un lien vers une entrée dans le Glossaire.

Références croisées et liaisons

Vous pouvez lier à un autre document dans le manuel avec :

:doc:`The Title </section/path/to/file>`

Pour lier à une section spécifique dans un autre document (ou le même), des étiquettes explicites sont disponibles :

.. _sample-label:

[section or image to reference]

Some text :ref:`Optional Title <sample-label>`

Liaison à un titre dans le même fichier :

Titles are Targets
==================

Body text.

Implicit references, like `Titles are Targets`_

Liaison au monde extérieur :

`Blender Website <https://www.blender.org>`__

Structure de répertoire

Les sections devraient être généralement structurées de la manière suivante :

  • directory_name/
    • index.rst (contient des liens aux fichiers internes)

    • introduction.rst
    • section_1.rst
    • section_2.rst

Par exemple :

  • rendering/
    • index.rst
    • cycles/
      • index.rst
      • introduction.rst
      • materials/
        • index.rst
        • introduction.rst
        • volumes.rst

L’idée est de mettre tout le contenu d’une section dans un même dossier. Idéalement chaque section devrait avoir un index.rst (contenant la table des matières pour cette section) et un introduction.rst (introduisant) au contenu de la section.

Table des matières

Par défaut, une table des matières devrait montrer deux niveaux de profondeur :

.. toctree::
   :maxdepth: 2

   introduction.rst
   perspective.rst
   depth_of_field.rst

Références complémentaires

Pour apprendre plus sur reStructuredText, consultez :

Sphinx RST Primer

Bonne introduction de base.

Docutils reStructuredText reference

Liens vers la documentation de référence et celle de l’utilisateur.