Make sphinx a soft dependency or factor out docstring parsing
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
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
NumpyDocStringout 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!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with pyproject.toml and the NumpyDocString and SphinxDocString implementations to map the hard dependency and the Sphinx-specific code. Review the linked napari use case and SciPy vendored implementation, then determine whether a soft dependency or separate library is the agreed direction; done requires a decided architecture and validated downstream use without an unnecessary Sphinx dependency.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100