-
Notifications
You must be signed in to change notification settings - Fork 2k
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
Resolve directives before running napoleon #9939
Comments
Did some more digging and I guess I understand now why this doesn't work. IISC the order of things is as roughly follows:
The important part is that napoleon works on the docstrings before it passes through docutils. From my understanding that means that there is no easy solution without completely reworking napoleon to work on the output of docutils instead. E.g. I first thought that overridig Now ofc this is a somewhat special usecase, so I'd be willing to type the docutils parameter definitions instead - but unfortunately that doesn't work either. The issue is that napoleon thinks that If my original request is too complicated & special case to consider, I'd like to ask to at least make napoleon properly handle |
Yes, your understanding is correct. As you said, it's difficult to support your request.
It means we have to reinvent the docutils parsers and directives only for napoleon because we can't use existing docutils parsers and directives (they return doctree instead of text!). So we need to create an "include" directive that returns text block instead. Additionally, we'll receive requests for supporting other directives if we'll support the "include" directive once. It must be a tough topic for us. |
All right, thanks for the confirmation!
Sorry, I should have made myself more clear. What I meant is that if resolving directives before running napoleon is too complicated, then it would be nice if napoleon didn't try to convert directives into docutils synatx. I.e. when running napeolen, it would convert
into
instead of the current output
I didn't go through the internals of lines[:] = (line.replace(':param .. include:: params.rst:', '.. include:: params.rst') for line in result_lines) |
Is your feature request related to a problem? Please describe.
At python-telegram-bot, we have many methods that require the same types of arguments, which should also get the same docstring. E.g. search for "chat_id (int | str) – Unique identifier for" at https://python-telegram-bot.readthedocs.io/en/stable/telegram.bot.html.
It would be helpful if one could write all those parameter specifications at a central place and import them as needed. This works when not relying on napoleon - e.g.
renders correctly if
params.rst
contains additional parameter definitions in the same style. When trying to do the same with Google docstrings + napoleon, i.e.this will render to a parameter
include: (.) – params.rst:
Similarly, adding something like
.. include:: note.rst
in the docstring but outside of theArgs:
will render the note contained innote.rst
correctly only if it's given as.. note:: …
instead ofNote: …
Describe the solution you'd like
It would be nice if directives would be resolved before napoleon parses the docstrings so that these kinds of things would work (also with other & custom directives)
Describe alternatives you've considered
I tried inserting the text via a
SphinxRole
subclass, but realized that for that I would have to parse the docstring manually, so I gave up on thatAdditional context
I haven't really understood the order in which sphinx reads the files, reads docstrings via autodoc, resolves directives, and applies napoleon or how that order is determined. If you can point me in the right direction, I'd be happy to try & PR for this.
The text was updated successfully, but these errors were encountered: