Style guide
We highly encourage you to obey established style guides for writing documentation. This page includes:
Writing Style Guide (writing rules)
Markup Style Guide (markup syntax)
Writing Style Guide
Rules to follow when writing documentation pages
Goals
Overall goals for writing documentation:
- User Relation
The documentation is created for users educated in CG, especially the Blender application and its workflow. The user should be familiar with texture baking, and what it stands for. But at the same time explicable for beginners and proficients, as far as baking can be complex in particular areas.
- Concise
Baking involves many aspects that can become hard and unnecessary to be documented. BakeMaster Documentation should include particular information and description regarding its functionality and features.
- Complete
Documented features should be provided with an understandable explanation covering the whole feature, its purpose range of usage and grouped under the appropriate topic.
- Polished
The described topic should follow the established documentation style.
Content Writing
Recommended:
Use American English
Check spelling and grammar
Make it simple, but fulfilled appropriately
Keep the sentence length between 4 and 12 words
If you don’t know what the feature you are documenting refers to, ask someone else before writing.
Paragraphs like Note that, Attention here, a warning should be placed in specific markdown admonition directories
Follow the existing documentation structure to know where to place a short description, and a full one.
Place enumerations or similar content in a list or table.
Avoid:
Long unseparated paragraphs (hard to read)
Writing in the first person
Vague language and weasel words
Long explanation if there is a simpler way to do it
Repeating information - better put a reference link
Markup Style Guide
The documentation is written in reStructuredText format files (.rst). This page is a quick tutorial about how to get around the reStructuredText markup syntax used in the BakeMaster docs.
Headings
==========
Page Title
==========
Section
=======
Subsection
----------
Subsubsection
*************
Another Section
===============
Subsection
----------
Note
Only one Page Title can exist on the page.
Paragraphs
This is a simple paragraph. It describes some information
about an important feature. This is a simple paragraph.
It describes some information about an important feature.
This is a simple paragraph. It describes some information
about an important feature. This is a simple paragraph.
It describes some information about an important feature.
Another simple paragraph that is a little shorter. It
describes some further information about an important
feature.
Note
Use the syntax below to write a paragraph with one-line blocks:
| This is a simple paragraph.
| The lines will break exactly how there are here.
| This is a simple paragraph.
Inline Markup
*italic text*
**bold text**
``literal``
Lists
- this is a bulleted list
- bullet list second item
1. this is a numbered list
2. this is a numbered list
3. this is a numbered list
* this is also a bulleted list
* this is also a bulleted list
* that has some subelements
* that has some subelements
* that has some subelements
* this is also a bulleted list
Renders into:
this is a bulleted list
bullet list second item
this is a numbered list
this is a numbered list
this is a numbered list
this is also a bulleted list
- this is also a bulleted list
that has some subelements
- that has some subelements
that has some subelements
this is also a bulleted list
Tables
+------------------------------+-------------------------------------------+
| Column heading | Column heading |
+------------------------------+-------------------------------------------+
| this is a simple table | description |
+------------------------------+-------------------------+-----------------+
| it can have nested structure | like this - two columns | in one frame |
+------------------------------+-------------------------+-----------------+
| bulleted list below | | one-line blocks |
+------------------------------+ | can be written |
| - item 1 | | with some *italic* text |
| - item 2 | |
| - item 3 | |
| | |
+------------------------------+-------------------------------------------+
Renders into:
Column heading |
Column heading |
|
this is a simple table |
description |
|
it can have nested structure |
like this - two columns |
in one frame |
bulleted list below |
one-line blocks
can be written
with some italic text
|
|
|
Code Blocks
...
use_bake : bpy.props.BoolProperty
...
Class code block like the one above can be written using a code-block
:
.. code-block:: python
:caption: properties.py
:emphasize-lines: 2
...
use_bake : bpy.props.BoolProperty
...
Properties and classes
- property map.use_bake
- class map
The class and the property above can be written using the syntax below:
.. py:property:: map.use_bake
:noindex:
.. py:class:: map
:noindex:
Images
Image with a caption under it:
.. figure:: /images/documentation/index_page/teaser_social_1200x600.png
Image caption.
Image reference:
.. |image_ref_name| image:: /images/documentation/index_page/teaser_social_1200x600.png
:alt: alternative text
:width: 600 px
:height: 300 px
:class: float-right
|image_ref_name|
This paragraph is a simple paragraph about some paragraphical paragrof.
Hint
:class: float-right
will make the image right-floated.
File Paths
:file:`docs/_static/css/theme.css`
Admonition Directories
.. note::
this is a short note.
.. attention::
attention here, please.
.. warning::
please keep in mind that...
.. DANGER::
Oh no! **frightened**.
.. tip::
Here is some tip.
.. hint::
There is a hidden treasure.
.. admonition:: Custom Admonition title
:class: seealso
Custom admonition with a ``:class:`` as its class type and text.
Render into:
Note
this is a short note.
Attention
attention here, please.
Warning
please keep in mind that…
Danger
Oh no! frightened.
Tip
Here is some tip.
Hint
There is a hidden treasure.
Custom Admonition title
Custom admonition with a :class:
as its class type and text.
Links, References and Cross-references
External link:
`Link Title <https://link-to-the-webiste>`__
Reference within the page:
.. _my_reference:
Document section
----------------
Some important text goes there. Some important text goes there.
Some important text goes there.
...
To reference that section, use :ref:`my_reference`.
For a reference to another document:
:doc:`Title /path/to/file`
Further Reading
To learn more about reStructuredText, you can visit the following websites:
- Sphinx RST Primer
A brief introduction to reStructuredText (reST) concepts and syntax
- Tutorial on GitHub
reStructuredText (RST) Tutorial