I have a Python package (https://github.com/frannerin/AlloViz)'s documentation (https://alloviz.readthedocs.io/) with the following structure:
AlloViz/docs/source
│ conf.py
│ index.rst
│ README.rst
│
└───API
│ index.rst
│ generate.rst # only has autosummary directive that is passed to autosummary_generate
│ # in the conf.py file to generate the .rst files in the generated/ folder
│
└───generated # Files generated automatically by autosummary extension with NumPy's templates
│ AlloViz.rst
│ AlloViz.Protein.rst # Protein class
│ AlloViz.Protein.calculate.rst # Protein class method
...
│ AlloViz.Delta.rst # Delta class
I am using Read the Docs to build and host my documentation, using numpydoc, autosummary (using NumPy's .rst templates) and the pydata-sphinx-theme. Currently, I have three headers (three elements in the main index.rst
file's toctree) in my documentation:
Then, source/API/index.rst
looks like this:
API reference
=============
.. toctree::
:caption: AlloViz
:maxdepth: 2
:hidden:
AlloViz.Protein <generated/AlloViz.Protein>
AlloViz.Delta <generated/AlloViz.Delta>
and it renders a page (https://alloviz.readthedocs.io/en/latest/API/index.html) that is empty:
But I would like that, when clicking to the "API reference" header at the top of the page, it showed directly the page corresponding to the AlloViz.Protein documentation (https://alloviz.readthedocs.io/en/latest/API/generated/AlloViz.Protein.html), which corresponds to a file generated by autosummary
inside the generated/
folder:
Using an .. include
directive in the API/index.rst
file to include the contents of the API/generated/AlloViz.Protein.rst
file doesn't work completely because it doesn't inherit the latter file's toctree inside it (which points to the class' methods), and also throws out warnings of duplicate members, and is just inelegant. I'm open to exploring whatever options if given some pointers!