numpy / numpy/numpydoc

Make sphinx a soft dependency or factor out docstring parsing

Open
#648 2 comments 2 reactions 0 assignees View on GitHub

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:

  1. See if sphinx can be made a soft-dependency within numpydoc
  2. 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!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.