********************************* 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 `__. Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. It is used by many open-source projects, including `Python `__, `NumPy `__, and `Matplotlib `__. Sphinx uses `reStructuredText `__ as its markup language, which is a lightweight markup language that is easy to read and write. Sphinx also supports `Markdown `__ and `LaTeX `__. 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 `__. 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 `__: .. 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 `. Also check out the `GitHub documentation `__ 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 `__ with your proposed changes and we will take care of the rest, or you can `contact us `__. 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 `__ 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! `__. .. 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 `__. 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 `__. 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 `__. 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 `__ and `Sphinx `__. If you find interesting features that you think would be useful for the OpenRocket documentation, please use them and document them here!