Search code examples
pythondocumentationpython-sphinxdocstring

Python sphinx documentation -- autosummary links not consistent using autodocsumm extension

I am generating documentation for a Python project using the Sphinx autodocsumm extension with the following autosummary configuration to show a summary of only classes at the beginning of the document.

 Module1 module
----------------------------

.. automodule:: src.Module1
   :members:
   :undoc-members:
   :show-inheritance:
   :autosummary:
   :autosummary-no-nesting:

In the generated html, the summary class name hyperlinks are not consistent -- one is a path to a separate summary stub file, while the other just references an anchor in the main src.html file.

file:///project_path/docs/_build/html/src.Module1/src.Module1.Class1.html#src.Module1.Class1
file:///project_path/docs/_build/html/src.html#src.Module1.Class2

I can't figure out why the classes are being treated differently during the make. The first one is a large class with many members while the second is a small class with just a few lines, so maybe there is some threshold for generating the stub file? My preference is to not reference a separate file and only jump to the respective anchor within the main document for all summary links.

Is there a setting to control this behavior?

Edit: Upon further review, I don't think this has anything to do with autodocsumm after all. I notice after doing the "make html" a subfolder is create only for the Class1 documentation while Class2 is referenced only in the main src.html file.

project_path/docs/_build/html/src.Module1/src.Module1.Class1.html
project_path/docs/_build/html/src.html

So... Why are these two classes treated differently? Also, is there any setting to prevent a separate folder and html file from being generated?

Solution

  • I finally figured out the issue... While narrowing my project down to a minimum reproducible example, I noticed an src.Module1 folder under docs that had rst files for Class1 only.

    Project
    docs
        _build
        src.Module1
            Module1.Class1.rst
            src.Module1.Class1.rst

    I'm not sure what I did to produced that folder, but after deleting it and rebuilding the Sphinx html, I am now getting the document anchors I expect directly in the src.html file:

    file:///project_path/docs/_build/html/src.html#src.Module1.Class1
file:///project_path/docs/_build/html/src.html#src.Module1.Class2