Contributing to the docs

How to edit, build, and style OpenRocket documentation using Sphinx and reStructuredText.

The OpenRocket documentation is written in reStructuredText, built with Sphinx, and hosted on Read the Docs. Source files live alongside the code in the repository under docs/source/.

Setting up the documentation build

1. Install dependencies

   Open a terminal in the docs/ directory and install the required Python packages:

   pip install -r requirements.txt
   
2. Build the docs

   From the docs/ directory, run:

   make html
   

   This generates the documentation in docs/build/html/. Open index.html in your browser to preview it.

3. Clean the build

   If you change the theme or the build configuration, clean the previous output first:

   make clean
   

Submitting changes

Edit the .rst files in docs/source/, then submit a pull request with your changes. If you are not comfortable with Git, open an issue with your proposed changes or contact us and we will handle it.

Style guide

Heading levels

ReStructuredText does not assign fixed decoration characters to heading levels — the hierarchy is determined by the order in which decorations first appear. OpenRocket docs use the following convention:

Level	Decoration	Usage
H1	* with overline	Chapter (page title)
H2	=	Section
H3	-	Subsection
H4	^	Subsubsection
H5	"	Paragraph

*****************************************
H1: This is a chapter (title of the page)
*****************************************

H2: This is a section
=====================

H3: This is a subsection
------------------------

H4: This is a subsubsection
^^^^^^^^^^^^^^^^^^^^^^^^^^^

H5: This is a paragraph
"""""""""""""""""""""""

The overline and underline must be the same length as the heading text.

Horizontal rules

Insert a horizontal rule before starting each new H2 section using four or more hyphens:

This is a section
=================

----

This is another section
=======================

Adding images

Images go in docs/source/img/, following the same directory structure as the source file. Use percentage widths and always include alt text:

.. figure:: /img/path/to/your/image.png
   :width: 60%
   :align: center
   :alt: Descriptive alt text
   :figclass: or-image-border

   Caption for the image.

Hyperlinks

`link text <https://example.com>`__

Always use a double underscore at the end (__). A single underscore can cause build errors when multiple links share the same display text.

To link to another page within the docs:

:doc:`link text </path/to/page>`

To link to a specific section:

:ref:`link text <anchor-name>`

Create an anchor with:

.. _anchor-name:

This is the anchored section.

Admonitions

Use admonitions to call out important information:

Tip

.. tip::

   This is a tip.

Note

.. note::

   This is a note.

Warning

.. warning::

   This is a warning.

Attention

.. attention::

   This is an attention notice.

Other available types: danger, error, hint, important, caution.

Semantic markup roles

Sphinx roles apply semantic meaning to inline text:

Role	Example	Use for
:menuselection:	:menuselection:File —> Open“	Menu navigation paths
:command:	:command:ls“	CLI commands
:file:	:file:conf.py“	File names and paths
:kbd:	:kbd:Ctrl + :kbd:C“	Keyboard keys
:guilabel:	:guilabel:Submit“	UI labels and buttons
:abbr:	:abbr:OR (OpenRocket)“	Abbreviations with tooltips

Substitutions

Custom substitutions are defined in docs/source/conf.py under rst_prolog. Use them to avoid repeating version numbers or other frequently updated values:

OpenRocket requires Java |java_vers|.

Line wrapping

Keep lines in .rst files under approximately 120 characters. Normal prose can be broken across lines freely — Sphinx treats adjacent lines as a single paragraph as long as there is no blank line between them.

For list items that span multiple lines, indent continuation lines to align with the start of the list item text.

Todo notes

Mark incomplete sections with a todo directive:

.. todo::

   This section is not yet finished.

Enable todo_include_todos = True in conf.py to render all pending todos in the output.