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
estGe2Kwy5EGE0
L’ID pour
https://vimeo.com/15837189
est15837189
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.