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.

Menus Opérateurs¶

Chaque opérateur doit recevoir son propre titre ou page en fonction de la longueur du contenu. Chaque opérateur doit avoir un avertissement de référence documentant le contexte de l’opérateur:

.. admonition:: Reference
   :class: refbox

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

Panneaux¶

Les panneaux doivent être documentés par leur propre titre, les panneaux imbriqués doivent utiliser des niveaux de titre décroissants. Chaque panneau peut avoir sa propre page en fonction de la longueur de la documentation et / ou du nombre de panneaux. Les menus développés qui basculent entre les propriétés présentées à l’utilisateur doivent être traités comme des sous-panneaux

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

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

Propriétés¶

Les propriétés doivent être documentées à l’aide de listes de définitions. Les propriétés qui sont masquées en fonction d’autres propriétés doivent utiliser des définitions imbriquées

Property
   Property description.

   Hidden Property
      Hidden property description.

Les menus basés sur les énumérations (enum)doivent être documentés en utilisant la syntaxe suivante

Menu Label
   General description of the menu.

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

Accès au Manuel Associé au Contexte¶

Il est possible de créer un lien vers une partie spécifique du manuel depuis Blender en cliquant avec le bouton droit sur une propriété ou un opérateur et en sélectionnant Online Manual. Pour que cela fonctionne, cela doit être pris en compte dans la documentation. Pour lier une propriété ou un opérateur à une partie spécifique du manuel, vous devez ajouter une balise de lien de référence externe dont l’ID correspond à la balise RNA de Blender. Le moyen le plus simple de savoir quelle est la balise d’une propriété est de cliquer avec le bouton droit sur la propriété / l’opérateur et de sélectionner Online Python Reference pour extraire la balise de l’URL. Quelques exemples de ce à quoi cela ressemble dans le document RST sont donnés ci-dessous

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

Pour un opérateur

.. _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/interface_splash_current.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(PavnumMoins – 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.

Join the 2%

Guide de style de balisage¶

Conventions¶

Entêtes¶

Style de texte¶

Éléments de l’interface¶

Menus Opérateurs¶

Panneaux¶

Propriétés¶

Accès au Manuel Associé au Contexte¶

Exemples de code¶

Images¶

Fichiers¶

Guides d’utilisation¶

Vidéos¶

Guides d’utilisation¶

Concepts utiles¶

Références croisées et liaisons¶

Structure de répertoire¶

Table des matières¶

Références complémentaires¶