Markup Style Guide¶
This page covers the conventions for writing and use of the reStructuredText (RST) markup syntax.
Three space indentation.
Lines should be less than 120 characters long.
Use italics for button/menu names.
Other loose conventions:
Avoid Unicode characters.
Avoid heavily wrapped text (i.e. sentences can have their own lines).
################# Document Part ################# **************** Document Chapter **************** Document Section ================ Document Subsection ------------------- Document Subsubsection ^^^^^^^^^^^^^^^^^^^^^^ Document Paragraph """"""""""""""""""
Parts should only be used for contents or index pages.
.rst file should only have one chapter heading (
*) per file.
See the overview on ReStructuredText for more information on how to style the various elements of the documentation and on how to add lists, tables, pictures and code blocks. The Sphinx reference provides more insight additional constructs.
The following are useful markups for text styling:
*italic* **bold** ``literal``
:kbd:`LMB`-- keyboard and mouse shortcuts.
*Mirror*-- interface labels.
:menuselection:`3D Viewport --> Add --> Mesh --> Monkey`-- menus.
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 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 =========
There is support for syntax highlighting if the programming language is provided,
and line numbers can be optionally shown with the
.. code-block:: python :linenos: import bpy def some_function(): ...
Figures should be used to place images:
.. figure:: /images/render_cycles_nodes_types_shaders_node.png Image caption.
For consistency, and since it would be good to ensure screenshots are all a similar size when floated next to text, writers should take screenshots in the following manner:
Prepare the area you would like to capture making sure to use the default theme and setting. (In some cases you may not want to use the default settings e.g. if some options are hidden behind a checkbox.)
Zoom to the maximum zoom level (hold NumpadPlus or Ctrl-MMB or similar).
Zoom out eight zoom levels (NumpadMinus -- eight times).
In some cases you will want to leave a small margin around the thing you are trying to capture. This should be around 30px but does not have to be exact.
This can be applied to several parts of the interface but might not work for all cases.
- No Caps, No Gaps
Lower case filenames underscore between words.
- Sort Usefully
Order naming with specific identifiers at the end.
.pngfor images that have solid colors such as screenshots of the Blender interface, and
.jpgfor images with a high amount of color variance, such as sample renders and photographs.
Do not use animated
.giffiles, these are hard to maintain, can be distracting and are usually large in file size. Instead use a video if needed (see Videos below).
Place the image in the
manual/imagesfolder. Use no other subfolders.
For naming files use underscores to separate chapters and sections, and use dashes to separate sections that are two or more words. So for image files should look like:
Do not use special characters or spaces!
Avoid specifying the resolution of the image, so that the theme can handle the images consistently and provide the best layout across different screen sizes.
When documenting a panel or section of the UI, it is better to use a single image that shows all of the relevant areas (rather than multiple images for each icon or button) placed at the top of the section you are writing, and then explain the features in the order that they appear in the image.
It is important that the manual can be maintained long term, UI and tool options change so try to avoid having a lot of images (when they are not especially necessary). Otherwise, this becomes too much of a maintenance burden.
Videos from YouTube™ can be embedded using:
.. youtube:: ID
ID is found in the video's URL, e.g:
The ID for
Avoid adding videos which rely on voice, as this is difficult to translate.
Do not embed video tutorials as a means of explaining a feature, the writing itself should explain it adequately (though you may include a link to the video at the bottom of the page under the heading
|BLENDER_VERSION|-- Resolves to the current Blender version.
:abbr:`SSAO (Screen Space Ambient Occlusion)`-- Abbreviations display the full text as a tooltip for the reader.
:term:`Manifold`-- Links to an entry in the Glossary.
Sections should be generally structured as follows:
index.rst(contains links to internal files)
The idea is to enclose all the content of a section inside of a folder. Ideally every section
should have an
index.rst (containing the TOC for that section) and an
(introducing) to the contents of the section.
Table of Contents¶
By default, a table of contents should show two levels of depth:
.. toctree:: :maxdepth: 2 introduction.rst perspective.rst depth_of_field.rst