Documentation ============= This doc details the structures and procedures used when writing documentation in and for Kubos products. Please refer to the :doc:`Kubos standards doc ` for more detailed documentation standards regarding things like naming and grammar. Generating The Docs ------------------- The Kubos docs are generated using `Sphinx `__ in conjunction with a variety of tools including `rustdoc `__ and `Doxygen `__. We suggest generating the docs from inside of the Kubos SDK environment, as it already has all dependencies installed. If you would like to generate the docs outside of the SDK environment, please refer to the following list of dependencies, in addition to the list of :ref:`build dependencies `. System dependencies: - doxygen - graphvis - plantuml - Python 3 + pip3 Python dependencies (most likely installed with ``pip3``): - Sphinx v1.5.6 - breathe v4.12.0 - sphinx-rtd-theme v0.2.4 - sphinxcontrib-plantuml - sphinxcontrib-versioning - sphinx-jsondomain In order to generate the entirety of the documentation locally, navigate to the top level of your copy of the Kubos repo and run ``tools/docs/gendocs.py``. The generated HTML files will be in the ``html`` folder, which you can then use to verify your new docs display as intended. To verify your docs: - Make sure that any new ``*.rst`` files are accessible through normal page clicks if you start at the top-level ``index.html`` - Verify that any new hyperlinks work as intended - Make sure that ``tools/docs/gendocs.py`` runs successfully without throwing any errors or warnings. Fix all warnings until the script runs cleanly. General Docs ------------ All docs files under ``docs/`` are written in the `reStructuredText `__ format. Please refer to the :doc:`standards doc ` for more specific writing standards. All executable projects, such as clients, examples, or services, should have a ``README.md`` which explains the purpose of the project, basic usage, and any runtime configuration options. Documenting Rust ---------------- The Rust book provides a pretty good overview of the standards for documenting Rust code `here `__. We leverage the ``cargo doc`` tool in generating our Rust documentation, so all Rust source is expected to conform to the standards laid out in the book. Documentation for any individual crate can be generated by running ``cargo doc`` from within that crate's folder. The generated docs can be found in ``kubos/target/doc/``. Including Rust Docs ~~~~~~~~~~~~~~~~~~~ The Rust docs generated by ``cargo doc`` will be placed in ``kubos/target/doc/``. These files are not accessible to the rest of the docs, so the contents of ``kubos/target/doc`` are moved to ``html/rust_docs`` during the documentation generation process. Adding a reference to the Rust docs just means adding a link to the appropriate html file: .. code-block:: rst This example references the |docs| for the file service. .. |docs| raw:: html docs Documenting Python ------------------ The Python source in the Kubos repo follows the `PEP 257 `__ docstring conventions. Public facing functions, classes, and modules should all be documented with the appropriate, descriptive docstrings. Including Python Docs ~~~~~~~~~~~~~~~~~~~~~ Any new python modules will need to be added to the ``python_modules`` list in `docs/conf.py `__ file so that Sphinx picks them up in the docs generation process. Documenting C ------------- Within the new modules's folder, create a ``docs`` subfolder and add a ``Doxyfile`` file. Feel free to copy ``Doxyfile`` from another C module, just change the ``PROJECT_NAME`` value. Within each header file of the module, add the following block to the top of the file in order for Doxygen to be able to process it: .. code-block:: c /** * @defgroup * @addtogroup * @{ */ And then add this to the bottom of the file: .. code-block:: c /* @} */ Within the header files, all items should be documented using `Doxygen's formatting `__. Including C Docs ~~~~~~~~~~~~~~~~ To include the new files in doc generation: - Add an entry to ``breathe_projects`` in `docs/conf.py` - Add an entry to ``DOCS_DIRS`` in `tools/docs/gendocs.py` The ``.rst`` doc should contain the declarations needed for the module documentation generated by Doxygen to be picked up and included in the final HTML: .. code-block:: rst .. doxygenfile:: module-header.h :project: module-name