At face value the title may sound absurd since numpydoc is a sphinx extension, but there are at least two use-cases that I'm aware of where libraries rely on the NumpyDocString class to work with numpydoc-style docstrings programmatically: see e.g. napari/napari#8322 and scipy's vendoring of the NumpyDocString class.
I believe the fundamental blocker for both of these use-cases is numpydoc's hard dependency on sphinx. I'm wondering whether it'd be possible to refactor things so that downstream libraries could depend on numpydoc without getting hit with the transitive sphinx dependency.
As I see it, there are two obvious paths to consider:
- See if sphinx can be made a soft-dependency within
numpydoc
- Split
NumpyDocString out into a separate, dependency-less pure Python library
At first glance option 1) seems possible to me as the sphinx-dependent stuff (e.g. SphinxDocString) is relatively self-contained; however the devil will almost certainly be in the details.
I think option 2 is more straightforward but involves setting up a separate project and a decent amount of code moving.
Anyways - just raising here so folks are aware of the motivating use-cases. If anyone has ideas/opinions about this scenario I'd be interested to hear them!
At face value the title may sound absurd since numpydoc is a sphinx extension, but there are at least two use-cases that I'm aware of where libraries rely on the
NumpyDocStringclass to work with numpydoc-style docstrings programmatically: see e.g. napari/napari#8322 and scipy's vendoring of the NumpyDocString class.I believe the fundamental blocker for both of these use-cases is numpydoc's hard dependency on sphinx. I'm wondering whether it'd be possible to refactor things so that downstream libraries could depend on numpydoc without getting hit with the transitive sphinx dependency.
As I see it, there are two obvious paths to consider:
numpydocNumpyDocStringout into a separate, dependency-less pure Python libraryAt first glance option 1) seems possible to me as the sphinx-dependent stuff (e.g. SphinxDocString) is relatively self-contained; however the devil will almost certainly be in the details.
I think option 2 is more straightforward but involves setting up a separate project and a decent amount of code moving.
Anyways - just raising here so folks are aware of the motivating use-cases. If anyone has ideas/opinions about this scenario I'd be interested to hear them!