.. _howto-doc: How to write documentation ========================== .. highlight:: rst Graphene uses `Sphinx`_ to generate the documentation in HTML form. The documentation is hosted on Read The Docs at https://graphene.readthedocs.io/. Documentation is generally written as `reStructuredText`_ files which are placed in ``Documentation/`` directory. See `Sphinx' reST primer`_ for short introduction into syntax. For code written in |nbsp| C, we use `Doxygen`_ and `Breathe`_, which is a |nbsp| Sphinx' plugin for including Doxygen documentation. Documentation of C |nbsp| language API should be written as Doxygen comments (see `Doxygen manual`_) and then included in one of the ``.rst`` files (with appropriate description) using one of the `Breathe directives`_, like ``.. doxygenfunction::`` or ``.. doxygenstruct::``. :ref:`Old Wiki ` is imported as it was, in Markdown, but new documentation should be written in reST. The documentation should be written with ``html`` builder of Sphinx in mind. The :file:`manpages/` subdirectory also targets ``manpage`` builder. Other builders (like ``latex``) may be considered in the future, but for now their output is not published. .. note:: A |nbsp| note about terminology: ``html``, ``latex`` and ``manpage``, and also others, are Sphinx "builders": http://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-b. Sphinx can output many different formats, some of them have overlapping usage (both ``html`` and ``latex`` usually output full handbook, the difference is screen vs print), some are specialised (``manpage`` processes only selected documents for man; those documents may or may not be also used by other builders). When launched through ``make`` (like ``make -C Documentation html``), this becomes "target" in Make terminology. Building documentation ---------------------- To build documentation, change directory to ``Documentation`` and use ``make``, specifying the appropriate target. The output is in the ``_build`` directory: .. code-block:: sh cd Documentation make html man firefox _build/html/index.html man _build/man/pal_loader.1 Preferred reST style -------------------- (This is adapted from `Python's style guide`_). - Use 3-space tab in ``.rst`` files to align the indentation with reST explicit markup, which begins with two dots and a |nbsp| space. - Wrap the paragraphs at 80th character. But don't wrap verbatim text like logs and use applicable style when wrapping code examples (see ``CODESTYLE.md`` in the repository). - For headers, use Python convention for header hierarchy: 1. ``#`` with overline, 2. ``*`` with overline, 3. ``=``, 4. ``-``, 5. ``^``, 6. ``"``. Example:: ################################### Very top level header (in TOC etc.) ################################### ******************* Less than top level ******************* Per-file header =============== Section header -------------- Subsection header ^^^^^^^^^^^^^^^^^ Subsubsection header """""""""""""""""""" This means most documents use only ``=`` and ``-`` adornments. .. tip:: For vim users: you can enter the ``-`` underlines using the key combination ``yypVr-`` and the other adornments with similar combinations. For Emacs users: Read more at https://docutils.sourceforge.io/docs/user/emacs.html. - Use ``|nbsp|`` to insert non-breaking space. This should be added after one-letter words and where otherwise appropriate:: This is a |nbsp| function. This substitution is added to all documents processed by Sphinx. For files processed also by other software (like ``README.rst``, which is both rendered by GitHub and included in ``index.rst``), use ``|_|`` after adding this substitution yourself:: .. |_| unicode:: 0xa0 :trim: This is a |_| README. Documentation of the code should be organized into files by logical concepts, as they fit into programmer's mind. Ideally, this should match the source files, if those files were organised correctly in the first place, but the reality may be different. In case of doubt, place them as they fit the narrative of the document, not as they are placed in the source files. Documents should be grouped by general areas and presented using ``.. toctree::`` directive in :file:`index.rst` file. This causes them to be included in TOC in the main document and also in sidebar on RTD. Preferred Doxygen style ----------------------- 1. Prefer Qt-style ``/*!`` and ``\param``: .. code-block:: c /*! * \brief An example function * * This function returns a number augmented by the Answer to the Ultimate * Question of Life, the Universe, and Everything. * * \param n The number to be added * \return A number 42 greater */ int foo(int n) { return n + 42; } :: There is a |nbsp| very special function :c:func:`foo`: .. doxygenfunction:: foo It's an example function, but is documented! 2. In reST, do not use ``autodoxygen`` directives, and especially do not use ``.. doxygenfile::``, because documentation should be written as prose, not a |nbsp| coredump. Write an explanation, how the things go together and place the ``.. doxygenfunction::`` directives where aproppriate. Further reading --------------- - `Four kinds of documentation`_ (`HN thread `__) - `The Hitchhiker's Guide to Documentation`_ divided by audience (role in the project), with references to good real-world examples .. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText .. _Sphinx: https://www.sphinx-doc.org/ .. _Sphinx' reST primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _Doxygen: http://www.doxygen.nl/ .. _Doxygen manual: http://www.doxygen.nl/manual/docblocks.html .. _Breathe: https://breathe.readthedocs.io/en/latest/ .. _Breathe directives: https://breathe.readthedocs.io/en/latest/directives.html .. _Python's style guide: https://devguide.python.org/documenting/#style-guide .. _Four kinds of documentation: https://www.divio.com/blog/documentation/ .. _The Hitchhiker's Guide to Documentation: https://docs-guide.readthedocs.io/en/latest/>