Skip to content

Make sphinx a soft dependency or factor out docstring parsing #648

@rossbar

Description

@rossbar

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!

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions