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 120 caractères de long.
Utilisez l’italique pour les noms de bouton/menu.

Autres conventions libres :

Éviter les caractères Unicode.
Évitez les textes trop longs (les phrases peuvent avoir leurs propres lignes).

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

Voici des 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 Viewport --> Add --> Mesh --> Monkey` – menus.

Operator Menus¶

Each operator should receive its own heading or page based on the length of the content. Each operator should have a reference admonition documenting the context of the operator:

.. admonition:: Reference
   :class: refbox

   :Mode:      Edit Mode
   :Menu:      :menuselection:`Curve --> Snap`
   :Hotkey:    :kbd:`Shift-S`

Panels¶

Panels should be documented by their own heading, nested panels should use decreasing heading levels. Each panel could have its own page based on the length of documentation and/or the amount of panels. Expanded menus that toggle what properties are presented to the user should be treated like subpanels:

Panel Title
===========

Nested Panel Title
------------------

Properties¶

Properties should be documented using definition lists. Properties that are hidden based on other properties should used nested definitions:

Property
   Property description.

   Hidden Property
      Hidden property description.

Enum based menus should be documented using the following syntax:

Menu Label
   General description of the menu.

   :Menu Item: Menu Item Definition.
   :Menu Item: Menu Item Definition.
   :Menu Item: Menu Item Definition.

Context Sensitive Manual Access¶

It is possible to link to a specific part of the manual from in Blender by right clicking on a property or operator and selecting Online Manual. In order for this to work, this needs to be accounted for in the documentation. To link a property or operator to a specific part of the manual you need to add an external reference link tag whose ID matches Blender’s RNA tag. The easiest way to find out what the tag for a property is to right click on the property/operator and select Online Python Reference to extract the tag from the URL. Some examples of how this looks in the RST document are given below:

.. _bpy.types.FluidDomainSettings.use_fractions:

Fractional Obstacles
   Enables finer resolution in fluid / obstacle regions (second order obstacles)...

   .. _bpy.types.FluidDomainSettings.fractions_distance:

   Obstacle Distance
      Determines how far apart fluid and obstacles are...

For an operator:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

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 figures devraient être utilisées pour placer les images

.. figure:: /images/render_cycles_nodes_types_shaders_node.png

   Image caption.

Dans un souci de cohérence, et puisqu’il serait bon que les captures d’écran soient toutes de taille similaire quand elles sont à côté d’un texte, les rédacteurs devraient prendre les captures d’écran de la manière suivante :

Préparer la zone que vous aimeriez capturer, en vous assurant d’utiliser le thème et le réglage par défaut (dans certains cas il est possible que vous ne voulez pas utiliser les réglages par défaut par ex. si certaines options sont cachées derrière une case à cocher).
Zoomer au niveau de zoom maximal (tenir PavnumPlus ou Ctrl-MMB ou similaire).
Dézoomer de huit niveaux de zoom(PavnumumMoins – huit fois).
Dans certains cas vous voudrez laisser une petite marge autour de la chose que vous essayez de capture. Ceci devrait être autour de 30px mais n’a pas à être exact.

Ceci peut s’appliquer à plusieurs parties de l’interface mais pourrait ne pas fonctionner dans tous les cas.

Fichiers¶

Pas de majuscules, pas d’espaces

Des noms de fichier 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. À la place utilisez une vidéo si nécessaire (voir Vidéos ci-dessous).

Emplacement

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

Nommage

Pour nommer les fichiers, utilisez le soulignement pour séparer les chapitres et les sections, et utilisez le tiret pour séparer les sections qui sont en deux mots ou plus. Ainsi pour les fichiers d’image, ils devraient être de la forme : chapter_subsection_sub-subsection_id.png, ex. :

interface_splash_current.png
interface_undo-redo_last.png
interface_undo-redo_repeat-history-menu.png

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

Guides d’utilisation¶

Évitez de spécifier la résolution de l’image, ainsi le thème peut gérer les images de façon cohérente et offrir 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^™ peuvent être intégrées en utilisant

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

Guides d’utilisation¶

Éviter d’ajouter des vidéos qui reposent sur la voix, étant donné que cela est difficile à traduire.
N’intégrez 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’entête Tutorials).

Concepts utiles¶

|BLENDER_VERSION| – règle 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.