Consider the following minimal example:
docs/index.rst
* :ref:`modindex`
docs/modules.rst
exampleproject
==============
.. toctree::
:maxdepth: 4
exampleproject
.. print_notes_attached_to_topic::
:topic: notes_about_someproblem
docs/conf.py
extensions = ['sphinx.ext.autodoc']
docs/exampleproject.rst
exampleproject package
======================
Module contents
---------------
.. automodule:: exampleproject
:members:
:undoc-members:
:show-inheritance:
exampleproject/__init__.py
def example_fun():
"""
This is the docstring I'll be discussing about.
.. attach_to_topic::
:topic: notes_about_someproblem
Grass is green.
"""
pass
def other_example_fun():
"""
This is the docstring I'll be discussing about.
.. attach_to_topic::
:topic: notes_about_someproblem
Sky is blue.
"""
pass
I know that sphinx.ext.autodoc can extract docstrings and put them within docs/exampleproject.rst. My question is: is there a way to also automatically append some sections to specific documents? Ideally I'd like to put as much as possible of my documentation in the source code, then use the source files of the documentation to put that information in a linear order. Something like:
- in example_fun docstring in
exampleproject/__init__.py, write expression "add a note to a section/topic named building_methods saying 'before running the project, do xyz'" - in index.rst, "list all notes tied to a section/topic named building_methods".
Comparison to autodoc
I know that sphinx has sphinx.ext.autodoc that processes docstrings of applications. The problem is that autodoc forces a certain "code-first" / "API-first" structure of the documentation. What I'm looking for is a solution that will let me keep as much of the documentation in the code as possible and then turn this documentation into a linear document, with data about certain topics extracted from something like the example attach_to_topic directive.
Is this possible with sphinx?
from Mixing code documentation with code by appending various notes to sections?
No comments:
Post a Comment