Only lowercase alphanumeric characters,
- (minus) symbol and the
.rst extension should be used.
It is preferred to use Notepad++ as the text editor for creating files. When creating a
.rst file tabs need to be replaced with a space indentation of
This can be accomplished easilly with Notepad++ by going to
Settings/Preferences/Language. In Language look to the right side for
Tab Settings, select
[Default] then check
Replace by space and set the Tab size: to
3. An example image is shown below.
All text should be on the same line. To make it easier to read turn on text wrap. In Notepad++ this feature is enabled by going to
Indentation and Blank Lines¶
Indentations should always match the previous level of indentation unless a new content block is created.
There should always be
1 blank line between everything. Except for lists.
.. tabs:: Example some stuff .. note:: some other stuff .. image:: images/fake-image-1.png :align: center
The highlight lines are the
1 blank line. Also note how there is no blank line between
.. image:: and
:align: as they are related and not seperate blocks.
To match other documentation use the following case for these terms exactly:
Visual Studio Code or VS Code
Images are easy to add and give a visual aspect to the user.
.. image:: images/example-image.png
Images should always be aligned to the center.
.. image:: images/example-image.png :align: center
If an image is to big or needs to be resized options such as width can be used to scale the image.
.. image:: images/example-image.png :align: center :width: 1000
Images should be stored in the same directory as the file using the image, located in a sub-directory
docs/Contributing/style-guide <- is the file docs/Contributing/images/style-guide-1.png <- image location
Supported image types:
If including a
.gif image a
.png static version of the same name is required to be included in the
images folder. This is required for a proper
If using a
.gif the format for the image would be this:
.. image:: images/example-image.* :align: center
Images should be named corresponding to the name of the file using it and incremented with a number enumerated to the end. Examples are shown below.
style-guide.rst would have the images
another-example.rst would have the images
Headings are signified with an underline with a specific symbol along with the heading character length. The following are the symbol levels to create heading:
=used for document titles and should only be used once
Document Title ==============
-signifies the chapters or sections
Chapter or Section ------------------
^signifies a new sub-section
New Sub-Section ^^^^^^^^^^^^^^^
~signifies a sub-sub-section
If a heading more than a sub-sub-section is required then in most cases it should be written another way
To create a block of code, use the
Line numbers are required for any block of code that contatains code. This is shown below. An exception for not having line numbers is when the code-block is just used for unformated text.
.. code-block:: (language) :linenos: Source code
Here is a simple Java example.
.. code-block:: java :linenos: System.out.println("Hello to whomever is reading this.");
Will come out as:
System.out.println("Hello to whomever is reading this.");
To higlight certain lines to stand out the
:emphasize-lines: is used.
.. code-block:: java :linenos: :emphasize-lines: 2,4 System.out.println("Hello to whomever is reading this."); System.out.println("I hope you learn something."); System.out.println("Its real important."); System.out.println("For success.");
Will come out as:
1 2 3 4
System.out.println("Hello to whomever is reading this."); System.out.println("I hope you learn something."); System.out.println("Its real important."); System.out.println("For success.");
The use of
2,3,4 is useful for single lines but for ranges
2-4 would work better. They can also be joined I.E.
There are two types of lists and they are easy to use.
- This is - a simple - bullet lists 1. This is 2. a simple 3. numeric list
List’s don’t require the
1 line blank space in-between like the other functions
Tabs are a useful tool with many uses.
A common use case in this documentation is Java and C++ tabs.
.. tabs:: .. tab:: Java .. code-block:: java :linenos: System.out.println("Hello World!"); .. tab:: C++ .. code-block:: c++ :linenos: std::cout << "Hello World!";
Would come out looking like:
For more information, vist Sphinx tabs.
Admonitions are a popup to indicate a warning or important information. The following are the possible admonitions; attention, caution, danger, error, hint, important, note, tip and warning. To utilize a admonition use the keywords admonition as a directive.
For ease of use place descriptions on the same line as the admonition.
.. attention:: Description
.. attention:: Description
Examples of each:
This is the attention admonition
This is the caution admonition
This is the danger admonition
This is the error admonition
This is the hint admonition
This is the important admonition
This is the note admonition
This is the tip admonition
This is the warning admonition