Documenting QMI

This section contains links that are useful while commenting QMI.

Section 7.3.6 of the Python Developers Guide 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

Wishlist for documentation

• Referencing to some items is quite hard to understand and get right.

• The annotated types are not clickable, so we add them parenthesized if important, now.

• Autosummary could help.

• Standard exception “ValueError” is not clickable (intersphinx?)