Usage question: Automatic generation of one page per member

[trendelkampschroer]

First of all thanks a lot for this great theme for sphinx documentations. The documentation generated with this theme looks amazing and is very readable.

Apologies if I am posting a question, that has already been answered elsewhere.

I am using the

.. autosummary
   :toctree: generated
   :recursive:

   TOP_LEVEL_PACKAGE_NAME

directive to get a complete documentation for the package when using sphinx-build. I am using conf.py from the sphinx-immaterial/docs folder as a template.

With autodoc_default_options = {"members": True, ...} the documentation for classes and functions appears on the same page as the one containing the summary table for the module.

Is it possible to instead put the documentation for each class/function on a separate page, cf. https://github.com/sphinx-doc/sphinx/issues/7912, which led me to spinx-immaterial in the first place.

Now I understand that there is the python-apigen-group directive, that supposedly achieves exactly this:

The summary of a group shows an abbreviated signature and an abbreviated description for each entity in the group; the name portion of the signature is a link to the separate page for that entity.

What's unclear to me is how I can ensure that python-apigen-group is applied for all groups (classes, functions, attributes, etc.) for each module automatically, i.e. I want sphinx-build to "automagically" generate .rst files for top-level package, sub-packages, modules, and module members where the package, sub-package, and module files contain autosummary tables for members. The table entry for each member then links to the page for the corresponding member.

Thanks a lot for your time and for developing and maintaining this great theme for sphinx.

[2bndy5]

how I can ensure that python-apigen-group is applied for all groups (classes, functions, attributes, etc.) for each module automatically

I thought this was possible by using the package's base module as the key:

python_apigen_modules = {
    "my_pkg": "my_pkg_api/",
}

Although, sub-modules/sub-packages that don't get imported by the package's base module would need their own entry in the config:

python_apigen_modules = {
    "my_pkg": "my_pkg_api/",
    "my_pkg.orphaned_module": "my_pkg_api/orphaned_module.",
}

I'm not aware of any plan to enhance the python-apigen such that everything under the package base is automatically included. As an alternative, it has been suggested (multiple times in this repo's issues) to make use of a manually maintained __all__ member for modules. Maybe that could be used in your package's base module to automatically include orphaned API components.

I want sphinx-build to "automagically" generate .rst files for top-level package, sub-packages, modules, and module members where the package, sub-package, and module files contain autosummary tables for members. The table entry for each member then links to the page for the corresponding member.

The "tables for members" bit makes this sound like you want the python-apigen ext to behave exactly like autosummary does. Did I understand that correctly?

[trendelkampschroer]

First of all, thanks for your quick reply, your suggestions, and taking time to reply to my question.

If possible I'd like to not rely on something that needs to be maintained manually in order for the documentation to track or reflect the changes in the source tree, except for a renaming or move of the top level package.

autosummary is attractive in the sense that the auto-generated summary tables with short descriptions extracted from the first line of the module/function/class provide a concise overview over a modules contents and an intuitive way to navigate to the more detailed documentation of classes/functions. But if I can achieve a similar result via a different route then my mind is not set on using autosummary.

I have to admit though, that I am a bit confused/overwhelmed with all the different tools, directives, etc. that can be used to generate the documentation, e.g. autosummary, autodoc, apigen,etc. And I have no clue which ones should/can be used in conjunction with sphinx-immaterial.

For example I'd like to understand more about the interaction of the python_apigen_modules configuration in conf.py and the various sphinx directives in e.g. index.rst.

I might just have overlooked something obvious in the documentation. Any pointers are more than welcome.

Thanks a lot.

[2bndy5]

I think autosummary is what you are looking for, and it can be used with this theme (like most of the Sphinx extensions out there). I say this because the python-apigen is much younger in comparison to autosummary and takes a slightly different approach to the same situation.

There are others like python-apigen, but listing recommendations is actually outside the scope of these issues/threads.

Personally, I prefer to use autodoc because the finite control better suites my documentation writing style. So, I guess it really depends on your writing style

---

As for adding intuition to python-apigen, I leave that up to jbms; I'm really only here to help keep this project alive.

For a deeper understanding of the python-apigen inner workings, you can explore the source code. Pay attention to any doc strings provided. Otherwise, jbms (the python-apigen author) would be better suited to explain specifics. Beware that the source heavily depends on inner workings of autodoc and autosummary. To be a bit more graphic about where some functionality comes from:

graph TB
  autodoc --> autosummary
  autodoc --> python-apigen
  autosummary -.-> python-apigen