Process docstring event v2 #131
Conversation
Add hawkmoth-process-docstring event that other Sphinx extensions can connect to, and enable extending the docstring processing using extensions instead of cautodoc_transformations. This is similar to the autodoc-process-docstring event [1]. Fixes #52. [1] https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#event-autodoc-process-docstring
It's difficult to document events properly with rst syntax. Sphinx documentation uses a custom 'event' object type, but the full implementation of it is a bit much. Just define the type, and use py:function for the event signature within the event description. It's a bit hackish, but gets the job done. (It's not possible to use py:function on the event directly, because the hyphens don't work in the function name.)
If the transformation is handled using an extension via event, it's okay to a) not have cautodoc_transformations defined, and b) not have the transform present in cautodoc_transformations. The flip side is that this is slightly less user friendly for cautodoc_transformations users with misconfiguration.
Transformations via cautodoc_transformations will be deprecated in some future release of Hawkmoth in favor of using hawkmoth-process-docstring event. However, we can already move cautodoc_transformations handling to an extension that is, for now, setup by default. In the future, we can still keep the extension, but have users explicitly set it up in conf.py if they need it. And later on, we can remove the extension from Hawkmoth altogether. This also marks the beginning of built-in extensions to Hawkmoth in hawkmoth.ext.
doc/built-in-extensions.rst
Outdated
| directly instead of :py:data:`cautodoc_transformations`. This built-in | ||
| extension provides backward compatibility for the functionality. | ||
|
|
||
| For now, this extension is loaded by default, and the below installation step |
There was a problem hiding this comment.
The installation step below*
| The extension has a few configuration options that can be set in ``conf.py``. | ||
|
|
||
| See also additional configuration options in the :ref:`built-in extensions | ||
| <built-in-extensions>`. |
There was a problem hiding this comment.
I'm really nitpicking here, but this feels inferior to the admonition style example I made. Particularly, it's less direct in stating that there is a specific extension which is temporarily enabled by default and thus its configuration variables are a non-negotiable addition to these ones. I think it's that extension that we need a reference for here, not the whole set.
Than again... meh.
|
I was expecting some notice of unstable API for the event. After what we discussed I think it would be a good idea, even if it will be relatively easy to support these APIs well into the future. I'll trust your judgment on that one though. Found a tiny grammatical and one other nitpick, but it's good really. Certainly no need for another round. This project is starting to shape up :) |
Add a Sphinx and Hawkmoth extension for docstring processing via the hawkmoth-process-docstring event to handle javadoc comments.
Add a proxy extension for processing napoleon formatted docstrings. It sets up napoleon properly, including its configuration options.
Stop using cautodoc_transformations and switch to using the built-in hawkmoth-process-docstring extensions for the transformations instead.
jnikula
force-pushed
the
process-docstring-event-v2
branch
from
ba000ab
to
3bbc7c5
Compare
I fixed the grammar, and merged this. We can tweak the rest before the next release if we want. Thanks for the review!
👍 |
v2 of #129 hopefully with all the comments resolved.
I've added some commits cleaning up related documentation, and expanded on the built-in extension usage. There's more to do, surely, but I'm hoping this is a good first step.
I also pushed the rebased but otherwise unchanged version of #129 to
process-docstring-event-v1-rebasedwhich may be helpful in comparing the differences between the two.