===============
Documenting QMI
===============

This section contains links that are useful while writing Sphinx documentation for QMI.

`Section 7.3.6 of the Python Developers Guide <https://devguide.python.org/documenting/#sections>`_ describes heading order. In our documentation, we start with the 'sections' level.

|    # with overline, for parts
|    * with overline, for chapters
|    =, for sections
|    -, for subsections
|    ^, for subsubsections
|    ", for paragraphs

--------------------------
Useful Documentation Links
--------------------------

Sphinx Cheat Sheet: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html

The *sphinx* documentation: http://www.sphinx-doc.org/en/master/

The *docutils* documentation: http://docutils.sourceforge.net/docs/index.html

Sphinx reStructuredText primer: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Documentation of the Sphinx *autodoc* extension: http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

Documentation of the Sphinx *autosummary* extension: http://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html

Documentation of the Sphinx *napoleon* extension: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

Documentation of the Google Python style guide: https://google.github.io/styleguide/pyguide.html

-------------------
Napoleon directives
-------------------

The following terms are recognized by the *Napoleon* parser:

* Args (alias of Parameters)
* Arguments (alias of Parameters)
* Attention
* Attributes
* Caution
* Danger
* Error
* Example
* Examples
* Hint
* Important
* Keyword Args (alias of Keyword Arguments)
* Keyword Arguments
* Methods
* Note
* Notes
* Other Parameters
* Parameters
* Return (alias of Returns)
* Returns
* Raises
* References
* See Also
* Tip
* Todo
* Warning
* Warnings (alias of Warning)
* Warns
* Yield (alias of Yields)
* Yields