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.

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

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

  2. Zoomer au niveau de zoom maximal (tenir PavnumPlus ou Ctrl-MMB ou similaire).

  3. Dézoomer de huit niveaux de zoom(PavnumMoins – huit fois).

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

Location

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, par exemple :

  • 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 peuvent être intégrées à partir de l’instance auto-hébergée PeerTube de Blender, qui se trouve à video.blender.org. Pour intégrer une vidéo en utilisant la directive suivante :

.. peertube:: ID

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

L’ID de https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c est 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c.

Pour télécharger une nouvelle vidéo, contactez un Administrateur du projet de documentation ou incluez la vidéo téléchargée dans votre description de votre Pull Request.

Guides d’utilisation

  • Évitez d’ajouter des vidéos qui reposent sur la voix ou les mots, é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 Tutoriels).

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>`__

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 ouvrant le menu contextuel (clic droit) d’une propriété ou d’un opérateur et en sélectionnant Online Manual (Manuel en ligne). 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 connaître la balise d’une propriété est d’ouvrir le menu contextuel de la propriété/de l’opérateur et de sélectionner Online Python Reference (Référence Python en ligne) 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
=========

Références complémentaires

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