Sphinx seems to be fairly centred around docstrings.
docstrings
- sections with colons:
- e.g. args, returns, raises i.e. arguments, what functions returns and exceptions functions may raise
- can insert custom sections
autodoc
In the context of Sphinx, autodoc is an extension that automatically generates documentation from docstrings in your Python code, allowing you to maintain up-to-date documentation directly from the source code comments.
reST is widely used in Python documentation and Sphinx.
RST syntax
reStructuredText (reST) file format has a specific syntax used primarily for technical documentation. Here are some key elements:
Headings
• Headings: Created using underlines and overlines with characters like =, -, ~, etc.
Lists
• Lists: Both ordered and unordered lists are supported using -, *, or numbers.
Links
• Links: Inline links can be created using backticks and underscores, like link text <URL>_.
Directives
• Directives: Special blocks for additional functionality, like .. note:: or .. code-block::.
Emphasis
• Emphasis: Italics and bold are created using * and **, respectively.
roles
inline markup within rst file. styling, linkking is associated with a role
Directive vs Roles
In Sphinx, directives and roles serve different purposes for documentation:
• Directives: These are block-level elements that can contain multiple lines of content. They are used to create complex structures like tables, code blocks, or admonitions. Directives are introduced with a double colon (::) and can include options and arguments. For example, the .. note:: directive creates a note box. • Roles: These are inline elements used to apply specific formatting or behavior to a piece of text. They are prefixed with a colon (:) and are used for things like cross-references, emphasis, or inline code. For example, the :ref: role creates a hyperlink to a section.
Both are essential for creating rich, structured documentation in Sphinx.