sphinx.ext.autosummary - document private objects?
#12858
Comments
It seems the solution is using a custom template that includes private members, see python-sphinx autosummary for private members. |
|
Thanks for your reply @electric-coder. I found that thread as well, but it doesn't really give a solution. I tried with a custom template, but the available variables (see above) explicitly address public objects. I also tried with the
it only gives me the dunders |
|
I managed to include the private modules manually, but that defeats the purpose of autosummary. For reference, I modified the {%- block modules %}
{%- if modules or name == 'my_module_containing_only_private_submodules' %}
.. rubric:: Modules
.. autosummary::
:nosignatures:
:toctree:
:template: custom-module-template.rst
:recursive:
{% for item in modules %}
{{ item }}
{%- endfor %}
{%- if name == 'my_module_containing_only_private_submodules' %}
_private_submodule_a
_private_submodule_b
{% endif %}
{% endif %}
{%- endblock %}(partially based on this StackOverflow entry / 7912) |
|
@bimac if you have a Stack Overflow account I'd advise also posting the last answer with the template there to help future users find it. You can write your own question and autoanswer it, or post under this Q since it's the easiest to find. autosummary is limited and not very flexible. Generally I advise using autodoc+napoleon and generating autodoc directives that include all members because if you've gotten to the point of writing a custom template you're likely to get better results with the same amount of work by just using autodoc. The note at the top of customizing templates already says this:
|
|
Thanks for your advice @electric-coder - I added my approach as an answer to the Stack Overflow question you mentioned. As to your point of using |
I think However much the project is convoluted/changing keeping one declaration per module still seems reasonable (using autosummary is equivalent to not having to maintain any rst at all). |
|
Thanks a lot! I played around with the pure autodoc approach a bit - it would probably be feasible if it were able to recurse into packages (which indeed it isn't). But with the amount of modules I'm facing this is not really an option. Also, by its nature this creates a single, long page ... Maybe I should also look into structuring my project a bit better ;-) |
I've been trying to build an API documentation with the recursive variant of
sphinx.ext.autosummarythat needs to include a few private modules of a package. Unless I missed something, it seems like I can only address public objects (functions,classes,exceptions,methods,attributes, andmodules) using Jinja templates.Is there any way of including private objects? Perhaps,
sphinx.ext.autosummarycould include all objects for whichautodoc-skip-member()returnsFalse, or offer a simliar mechanism?Thank you!
The text was updated successfully, but these errors were encountered: