-
Notifications
You must be signed in to change notification settings - Fork 27
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support for autosummary :recursive: documentation of entire API #33
Comments
I'd like to add my voice to this, have just run into this exact problem today and would love it if this would fit into the recursive command along with everything else. For now I'm going to just ignore the pydantic files as I don't quite understand the workaround, unfortunately. If anyone (@Yoshanuikabundi ?) could explain it, I'd be very grateful though. |
@Yoshanuikabundi Thanks for your detailed report and your thoughts on this issue. I know it's a pity that a fully automated API documentation does not yet work properly with Unfortunately I haven't had enough time to take a deep dive on this issue, yet. But judging from a high level perspective, I assume effort is best invested in extending I hopefully will come back to this soon. Providing a PR to sphinx with the required functionality also shouldn't be too difficult. |
I think I've narrowed it down. Try this with conf.py
index.rst
test.py
Thanks for making this package, by the way! |
The error it generates for me is as follows:
|
@StephenHogg I think your
|
@Yoshanuikabundi I took a closer look at your proposal. It is a good idea to extend the standard autosummary template to call the custom function However, providing the function to the jinja template namespace is currently not possible because the jinja template environment (which needs to be accessed to register a function) is created here: There is no proper way to access the jinja environment without monkeypatching this class :-(. A dirty fix to allow to: ns['classes'], ns['all_classes'] = \
get_members(obj, {'class', 'pydantic_model', 'pydantic_settings'}, imported=imported_members) This change will make Of course, both solutions are just workarounds. I'm going to provide a PR upstream to sphinx to address sphinx-doc/sphinx#6264 as this should not be too complicated. The best solution should make the standard templates extensible without overwriting them completely. Instead, it should be possible to add custom sections to them template while also modifying the jinja namespace template as you've proposed. But this is more complicated. |
@mansenfranzen Thanks for the update! I think I completely agree with you. I thought the Jinja2 environment was extensible because autoapi provides a very clean API to modify it, but on closer inspection it looks like they can do this because they use their own templates rather than extending those of Autosummary. Sorry about that! I definitely think fixing that upstream issue is a much better solution and I'm very grateful that you're taking a shot at it! Let me know if you need another set of eyes on it. @StephenHogg Sorry for the confusion! My workaround was a proposal, not something I had working. |
Hi, I'm just wondering if there's any update on this issue? |
Unfortunately not - I haven't gotten any response in the upstream issue sphinx-doc/sphinx#6264. I just added a friendly reminder. |
Hi all! I've come up with a template that works around this issue for the time being. Adding the Minimal template (goes in {% extends "!autosummary/module.rst" %}
{% block classes %}
{% set types = [] %}
{% for item in members %}
{% if not item.startswith('_') and not (item in functions or item in attributes or item in exceptions) %}
{% set _ = types.append(item) %}
{% endif %}
{%- endfor %}
{% if types %}
.. rubric:: {{ _('Classes') }}
.. autosummary::
:toctree:
:nosignatures:
{% for item in types %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %} More realistically you might want to also add |
Thanks for sharing - that's really great! This information could be very useful for others, too. It would be a great candidate for the documentations FAQ section. If you feel motivated and you have enough time, you could a PR to extend the FAQ section with your workaround. If not, no worries - I can also do it. |
I'd love to! But it might take me a while to get to, so if it's a priority for you don't feel like you have to wait for me. |
@Yoshanuikabundi No need to hurry - take your time. |
Thanks for @Yoshanuikabundi 's ideas, I implemented a custom autosummary extension. (I was having many issues with other non-pydantic types falling into the "types" list in his template and I wanted more control over the pydantic behavior.) I simply copied the Edited Then in
In the
Then in All the standard autosummary settings will still work with no changes. I use this with custom templates (optional) to do toctree and custom pydantic settings, so in my module template:
And then
Hope this helps someone. |
@iwyrkore Thanks for sharing your solution! I'm sure it will be helpful for others having the same issue. I might add a new section to the user's FAQ docs soonish linking to your solution, too (feel free to create PR yourself if you want to ;-)). |
@all-contributors please add @iwyrkore for code |
I've put up a pull request to add @iwyrkore! 🎉 |
@iwyrkore Specifically how and where did you change the init and generate imports? I can't seem to get this to work, even though I added docs/ext/pydantic_autosummary to my path in conf.py. When making the html, it still defaults to the lib/site-packages/sphinx/ext/autosummary package instead of using my custom defined one :( |
Hi! Thanks for this package, I love the results it produces!
I've been experimenting with ways to fully automate the generation of API reference documentation from source code and docstrings, a la rustdoc. I know you're aware of this, but there's no easy way to include
autodoc_pydantic
output in a fully automated API reference.The following works, of course:
But I would like the following:
I understand that the reason this doesn't work is that Sphinx doesn't let you expose new variables to the autosummary templates (as you discuss in #11). I've worked around this to some extent in the project I'm working on by adding an autosummary table with all the members not documented elsewhere in the template to the end of the module template, but it's not very good and we probably won't end up using it.
My suggestion would be to workaround the bug in Sphinx by adding a Jinja2 filter along the lines of "keep_pydantic_models" that takes an iterator of names of objects and filters out those that aren't models. So a block like the following could be added to an Autosummary template:
I think you should be able to add such a filter to all templates, but I'm not super familiar. Sorry if this isn't helpful.
Thanks!
The text was updated successfully, but these errors were encountered: