openrocket/docs/source/dev_guide/contributing_to_the_docs.rst

*********************************
Contributing to the Documentation
*********************************

This document explains how to contribute to the OpenRocket documentation. It provides information on why we use Sphinx
for our documentation, how to edit and build the documentation, and the style guide for writing documentation.

.. contents:: Table of Contents
   :depth: 2
   :local:
   :backlinks: none

Why Sphinx?
===========

This documentation is generated using `Sphinx <https://www.sphinx-doc.org/en/master/>`__. Sphinx is a tool that makes it
easy to create intelligent and beautiful documentation. It is used by many open-source projects, including
`Python <https://www.python.org/>`__, `NumPy <https://numpy.org/>`__, and `Matplotlib <https://matplotlib.org/>`__.
Sphinx uses `reStructuredText <https://docutils.sourceforge.io/rst.html>`__ as its markup language, which is a lightweight markup language that is easy to read and write. Sphinx also supports `Markdown <https://www.markdownguide.org/>`__ and `LaTeX <https://www.latex-project.org/>`__.

Previously, OpenRocket used MediaWiki for its documentation, but we decided to switch to Sphinx for several reasons:

- Sphinx is more powerful, modern, and flexible than MediaWiki. It allows us to create more complex and interactive documentation.

- Sphinx is easier to maintain than MediaWiki. It is easier to update and manage the documentation in the source files.

- Sphinx can give warnings and errors when building the documentation, which helps to catch mistakes and inconsistencies.

- The documentation is hosted on our GitHub repository, together with the source code. This ensures all resources are concentrated,
  makes it easier to keep the documentation in sync with the code, and allows for better version control.

- Lastly, for some users who wanted to contribute to the MediaWiki documentation, their access to the MediaWiki was blocked.
  We were never able to solve that issue.

Read the Docs
-------------

The OpenRocket documentation is hosted on `Read the Docs <https://readthedocs.org/>`__. Read the Docs is a popular
platform for hosting documentation for open-source projects. It automatically builds the documentation from the source
files in the OpenRocket repository and makes it available online. This makes it easy for users to access the documentation
and for contributors to update it. It also supports versioning, so you can view the documentation for different versions of
OpenRocket, and it has a search feature that allows you to quickly find what you are looking for. Additionally, you can also
add translations to the documentation, which makes it accessible to a wider audience.

Editing and Building the Documentation
======================================

If you would like to contribute to the documentation, you can do so by editing the reStructuredText files in the
:file:`docs/source` directory of the OpenRocket repo. You can then build the documentation by first
`installing Sphinx <https://www.sphinx-doc.org/en/master/usage/installation.html>`__:

.. code-block:: bash

    pip install sphinx

You'll also need to install some additional sphinx dependencies:

.. code-block:: bash

   pip install sphinx-rtd-theme
   pip install sphinx_new_tab_link

To build the docs, run the following command from the ``docs`` directory:

.. code-block:: bash

    make html

This will generate the documentation in the :file:`docs/build/html` directory. You can then view the documentation by opening the
``index.html`` file in your web browser.

To clean your build (necessary when you change the theme or make other changes to the build configuration), run:

.. code-block:: bash

   make clean


If you would like to contribute to the documentation, please submit a pull request with your changes. If you are not sure how to
do this, please see the ``Obtaining the Source Code`` section in :doc:`Development Environment Setup </dev_guide/development_setup>`.
Also check out the `GitHub documentation <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request>`__
on how to submit a pull request. If you don't want to go through the hassle of setting up a development environment, you can also
`submit an issue <https://github.com/openrocket/openrocket/issues/new/choose>`__ with your proposed changes and we will take care of the rest,
or you can `contact us <https://openrocket.info/contact.html>`__.

Style Guide
===========

This section provides a style guide for writing documentation for OpenRocket. It covers conventions that we use in the docs
and useful tips for writing reStructuredText/Sphinx docs.

Heading levels
--------------

Normally, in reStructuredText, there are no heading levels assigned to certain characters as the structure is determined
from the succession of headings. However, we have set the following heading level rules for the documentation:

- \# with overline, for parts *(not really used at the moment)*

- \* with overline, for chapters

- \= for sections

- \- for subsections

- \^ for subsubsections

- \" for paragraphs

Note that the overline and underline characters must be the same length as the text they are underlining.

For example:

.. code-block:: rst

    *****************************************
    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
    """""""""""""""""""""""

Adding Images
-------------

Images are added to the documentation like this:

.. code-block:: rst

   .. figure:: /img/path/to/your/image.png
      :width: 50% (please always express this as a percentage, and don't go over 95% width)
      :align: "left", "center", or "right" ("center" should be used in general)
      :alt: Alternative text
      :figclass: or-image-border (optional, for custom styling)

       This is the caption of the image.

Images are stored in the :file:`img` directory in the :file:`docs/source` directory. When adding images, please make sure
they are in the correct format (PNG, JPEG, or SVG) and that you place them in the correct directory. Use the same directory
structure as the rst source file that you want to include the image in. For example, if you want to include an image in
:file:`docs/source/user_guide/quick_start.rst`, place the image in :file:`docs/source/img/user_guide/quick_start/`.

Just for fun, here is an image of my cat:

.. figure:: /img/dev_guide/contributing_to_the_docs/Oscar.jpeg
   :width: 50%
   :align: center
   :alt: A cute cat
   :figclass: or-image-border

   This is a picture of my cat, Oscar.

Hyperlinks
----------

Hyperlinks to external sites are created like this:

.. code-block:: rst

    `link text <www.your_url.com>`__

Replace ``link text`` with the text you want to display as the hyperlink, and ``www.your_url.com`` with the actual URL
of the hyperlink. For example: `Hey, I'm a link! <https://www.youtube.com/watch?v=dQw4w9WgXcQ>`__.

.. warning::

   Always use a double underscore at the end. Don't use a single underscore, as this can cause issues when you have
   multiple hyperlinks with the same text.

Notes and Warnings
------------------

As you saw just above, you can add notes and warnings to draw attention to important information. More information can
be found `here <https://sublime-and-sphinx-guide.readthedocs.io/en/latest/notes_warnings.html>`__.

Create a note like this:

.. code-block:: rst

    .. note::

       This is a note.

Create a warning like this:

.. code-block:: rst

    .. warning::

       This is a warning.

Semantic Markup
---------------

Sphinx uses interpreted text roles to insert semantic markup into documents. They are written as \:rolename\:\`content\`.
More information can be found `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`__. What
this means is that you can add roles to pieces of text that have a specific meaning so that Sphinx renders that text
in an appropriate way. Below you find some of the most common roles used in the OpenRocket documentation:

\:menuselection\: Role
^^^^^^^^^^^^^^^^^^^^^^

The ``:menuselection:`` role is used to represent a sequence of menu selections in a user interface.

Example:
  :menuselection:`File --> Open example`

(Ensure you use the correct arrow character, which is ``-->``.)

\:command\: Role
^^^^^^^^^^^^^^^^

The ``:command:`` role is used to represent a command that a user can enter in a command-line interface.

Example:
  To list the contents of a directory, use the :command:`ls` command.

\:file\: Role
^^^^^^^^^^^^^

The ``:file:`` role is used to indicate a file or a file path.

Example:
  Open the configuration file :file:`conf.py` to modify the settings.

\:kbd\: Role
^^^^^^^^^^^^

The ``:kbd:`` role is used to indicate keyboard keys or shortcuts.

Example:
  Press :kbd:`Ctrl` + :kbd:`C` to copy the text.

\:guilabel\: Role
^^^^^^^^^^^^^^^^^

The ``:guilabel:`` role is used to indicate labels of GUI elements like buttons, labels, or fields.

Example:
  Click the :guilabel:`Submit` button to save your changes.

Substitutions
-------------

Sphinx allows you to define substitutions that can be used to replace text in the documentation. This is useful for
replacing frequently used text that is prone to update (e.g. versions of something, or dates). More information can be
found `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#substitutions>`__.
Custom substitutions are defined in :file:`docs/source/conf.py` in the ``rst_prolog`` section. For example, there is a
substitution for ``|java_vers|`` that defines the version of Java that OpenRocket requires. You can then use this
substitution in the documentation like this: OpenRocket uses Java ``|java_vers|`` (Java |java_vers|).

Escaping Special Characters
---------------------------

If you need to include a special character in your text that is normally interpreted by Sphinx, you can escape it by
preceding it with a backslash. For example, to include a backslash in your text, you would write ``\\``. To include
a colon, you would write ``\:``.

----

.. note::

   The reStructuredText syntax and Sphinx' capabilities are **very rich**. This page barely scratches the surface of what you can do.
   Please take the time to read the `documentation on reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`__
   and `Sphinx <https://www.sphinx-doc.org/en/master/usage/index.html>`__. If you find interesting features that you think would be
   useful for the OpenRocket documentation, please use them and document them here!