howto-doc.rst 2.5 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647
  1. .. _doc-howto:
  2. How to write documentation
  3. ==========================
  4. Documentation is generally written as `reStructuredText`_ files and processed
  5. using `Sphinx`_. See `Sphinx' reST primer`_ for short introduction into syntax.
  6. :ref:`Old Wiki <old-wiki>` is imported as it was, in Markdown, but new
  7. documentation should be written in reST.
  8. API documentation of C |nbsp| language should be written as Doxygen comments
  9. (prefer Qt-style ``/*!`` and ``\param``) and then included in one of the
  10. ``.rst`` files (with appropriate description) using one of the `Breathe
  11. directives`_, like ``.. doxygenfunction::`` or ``.. doxygenstruct::``. See
  12. `Breathe`_ documentation for more info. Do not use ``autodoxygen`` directives,
  13. and especially do not use ``.. doxygenfile::``, because documentation should be
  14. written as prose, not a |nbsp| coredump.
  15. In ``.rst`` files use 3-space tab. This is an uncommon value, but good value
  16. because intended blocks usually follow explicit markup, which begins with
  17. ``..``). Wrap the paragraphs at 80th character, but don't wrap verbatim text
  18. like logs and use applicable style when wrapping code examples. Use Python
  19. convention for header hierarchy: ``#`` with overline, ``*`` with overline,
  20. ``=``, ``-``, ``^``, ``"``. This means most documents use only ``=`` and ``-``
  21. underlines. Those underlines are easy to enter in :command:`vim` using the
  22. combination ``yypVr-``.
  23. Documentation of the code should be organized into files by logical concepts,
  24. as they fit into programmers mind. Ideally, this should match the source files,
  25. if those files were organised correctly in the first place, but the reality may
  26. be different. In case of doubt, place them as they fit the narration of the
  27. document, not as they are placed in the source files.
  28. Documents should be grouped by general areas and presented using
  29. ``.. toctree::`` directive in :file:`index.rst` file. This causes them to be
  30. included in TOC in the main document and also in sidebar on RTD.
  31. The documentation targets ``html`` output of Sphinx. The :file:`manpages/`
  32. subdirectory also targets ``manpage`` builder. Other formats (like ``latex``)
  33. may be considered in the future, but for now their output is neither published
  34. not cared for.
  35. .. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText
  36. .. _Sphinx: https://www.sphinx-doc.org/
  37. .. _Sphinx' reST primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
  38. .. _Breathe: https://breathe.readthedocs.io/en/latest/
  39. .. _Breathe directives: https://breathe.readthedocs.io/en/latest/directives.html