Docs fixes / improvements#483
Conversation
Currently, the methods heading is printed if there are any methods, including __init__, but __init__ is filtered out from the methods list and table. This can lead to the situation that if a class has only __init__ and no other public methods, the "Methods table" and "Methods" headings will be printed, but no actual methods will be documented. Move the methods filtering to the very beginning and overwrite the methods variable with the filtered version to prevent above problem.
With this change, one can apply autosummary to submodules of the package and have everything work.
The only difference to the default template is the addition of toctree directives for functions, classes, and exceptions. This enables one to pass a module to autosummary and have it generate documenation pages and crossreferences for all top-level functions, classes, and exceptions, not just for submodules.
|
The |
|
I did something similar here: scverse/anndata@2bd53b8 The |
print them in the first iteration
|
Done. Although I still like the previous version better: It only filtered in one place, now we have to filter in two places (methods table and methods docs). |
|
we could both re-define the variable and use the |
|
True, but then I don't really see a difference to my original approach, it's just moving the if block from outside the loop to inside the loop. |
|
Yeah, it’s just fewer |
|
If you think so. Done. |
this is necessary to make it pick up cross-references within the current class, e.g. :attr:`n_obs`.
ilia-kats
force-pushed
the
docs_fixes
branch
4 times, most recently
from
7f53761 to
420d613
Compare
This is necessary to have return types for properties. See discussion in scverse/mudata#130
|
I'm not a huge fan of adding yet another custom file to the sphinx configuration. Could this be part of |
|
If you're talking about the new extension, that's a workaround for sphinx-doc/sphinx#14264. I'm happy to also put it into scverse-misc (might go well with scverse/scverse-misc#37), scanpydoc, or wherever, but then the cookiecutter template should use that package by default. Also note that that extension is tightly integrated with the |
agree, if everything that is now a custom sphinx configuration in this cookiecutter template is covered by scverse-misc, I'm happy to depend on it by default. |
This moves the autosummary templates and custom Sphinx extensions from cookiecutter-scverse into our own Sphinx extension. See also the discussion in scverse/cookiecutter-scverse#483
3 participants
Various fixes for the autosummary templates. In particular:
don't print Methods table heading if there are no methods
Currently, the methods heading is printed if there are any methods, including
__init__, but__init__is filtered out from the methods list and table. This can lead to the situation that if a class has only__init__and no other public methods, the "Methods table" and "Methods" headings will be printed, but no actual methods will be documented. Move the methods filtering to the very beginning and overwrite the methods variable with the filtered version to prevent above problem.use fullname instead of objname in the class template
With this change, one can apply autosummary to submodules of the package and have everything work.
add a module.rst autosummary template
The only difference to the default template is the addition of toctree directives for functions, classes, and exceptions. This enables one to pass a module to autosummary and have it generate documenation pages and crossreferences for all top-level functions, classes, and exceptions, not just for submodules.