Re: Split docscrape out from numpydoc

--===============8356093133322123338==
Content-Type: multipart/alternative; boundary="000000000000c07959064fe69ed1"

--000000000000c07959064fe69ed1
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

Hi Lucas,

Indeed I think this is a good idea - SciPy is not the only project that
depends (or would like to have depended) on the NumpyDocString and
docscrape functionality without pulling in Sphinx (or any other dependency)=
.

One solution is to refactor numpydoc to fix the dependency footprint - i.e.
make sphinx a soft dependency. That work is mostly complete in
[numpy/numpydoc#651](https://github.com/numpy/numpydoc/pull/651). There are
a few final integration tests (see checkboxes in the top post in the PR)
that I'd like to run to build confidence that the solution works for
everyone. That should include replacing the vendored code in scipy.

Does this solution work for scipy?

On Mon, Apr 20, 2026 at 5:06=E2=80=AFAM Lucas Colley via NumPy-Discussion <
[email protected]> wrote:

> Hi all,
>
> A while ago I proposed splitting docscrape out from the numpydoc repo:
> https://github.com/numpy/numpydoc/issues/619.
>
> Why? SciPy has a copy of the docscrape source which is used to generate
> some docstrings for the public API. Copying source code like this is neve=
r
> great given that the two copies can fall out of sync. Vendoring the entir=
e
> numpydoc repo in SciPy, however, or adding numpydoc as a runtime
> dependency, seem off the table, making the situation worse rather than
> better.
>
> A better solution seems to be to have docscrape be a standalone project,
> which SciPy can vendor more easily, and which numpydoc can either depend =
on
> or vendor. From a modularity perspective at least this seems ideal =E2=80=
=94 there
> are use-cases where you want docscrape, but not numpydoc, available at
> runtime. Joren suggested that I float this idea on the mailing list, give=
n
> that he just submitted a patch to the copy in SciPy without realising tha=
t
> it was vendored code =F0=9F=98=84.
>
> What I don't know is whether this would negatively impact maintenance
> burden etc.? I assume there will be a bit of upfront cost in restructurin=
g
> the repos, and a little more if we decide to distribute docscrape as a
> standalone project, but my hope would be that this wouldn't cause any
> problems long-term?
>
> An alternative solution would be to extract the docscrape source from the
> numpydoc repo in a vendoring script in SciPy. While okay, that still leav=
es
> us having to track commits by hand instead of using e.g. a git submodule,
> and isn't robust to upstream changes of directory structure.
>
> Feedback appreciated! Eric Larson responded on the PR asking whether SciP=
y
> can introduce a dependency on numpydoc, but that is all so far.
>
> Cheers,
> Lucas
> _______________________________________________
> NumPy-Discussion mailing list -- [email protected]
> To unsubscribe send an email to [email protected]
> https://mail.python.org/mailman3//lists/numpy-discussion.python.org
> Member address: [email protected]
>

--000000000000c07959064fe69ed1
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div>Hi Lucas,</div><div><br></div><div>Indeed I think thi=
s is a good idea - SciPy is not the only project that depends (or would lik=
e to have depended) on the NumpyDocString and docscrape functionality witho=
ut pulling in Sphinx (or any other dependency).</div><div><br></div><div>On=
e solution is to refactor numpydoc to fix the dependency footprint - i.e. m=
ake sphinx a soft dependency. That work is mostly complete in [numpy/numpyd=
oc#651](<a href=3D"https://github.com/numpy/numpydoc/pull/651">https://gith=
ub.com/numpy/numpydoc/pull/651</a>). There are a few final integration test=
s (see checkboxes in the top post in the PR) that I&#39;d like to run to bu=
ild confidence that the solution works for everyone. That should include re=
placing the vendored code in scipy.</div><div><br></div><div>Does this solu=
tion work for scipy?=C2=A0</div></div><br><div class=3D"gmail_quote gmail_q=
uote_container"><div dir=3D"ltr" class=3D"gmail_attr">On Mon, Apr 20, 2026 =
at 5:06=E2=80=AFAM Lucas Colley via NumPy-Discussion &lt;<a href=3D"mailto:=
[email protected]">[email protected]</a>&gt; wrote:<br>=
</div><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;b=
order-left:1px solid rgb(204,204,204);padding-left:1ex">Hi all,<br>
<br>
A while ago I proposed splitting docscrape out from the numpydoc repo: <a h=
ref=3D"https://github.com/numpy/numpydoc/issues/619" rel=3D"noreferrer" tar=
get=3D"_blank">https://github.com/numpy/numpydoc/issues/619</a>.<br>
<br>
Why? SciPy has a copy of the docscrape source which is used to generate som=
e docstrings for the public API. Copying source code like this is never gre=
at given that the two copies can fall out of sync. Vendoring the entire num=
pydoc repo in SciPy, however, or adding numpydoc as a runtime dependency, s=
eem off the table, making the situation worse rather than better.<br>
<br>
A better solution seems to be to have docscrape be a standalone project, wh=
ich SciPy can vendor more easily, and which numpydoc can either depend on o=
r vendor. From a modularity perspective at least this seems ideal =E2=80=94=
 there are use-cases where you want docscrape, but not numpydoc, available =
at runtime. Joren suggested that I float this idea on the mailing list, giv=
en that he just submitted a patch to the copy in SciPy without realising th=
at it was vendored code =F0=9F=98=84.<br>
<br>
What I don&#39;t know is whether this would negatively impact maintenance b=
urden etc.? I assume there will be a bit of upfront cost in restructuring t=
he repos, and a little more if we decide to distribute docscrape as a stand=
alone project, but my hope would be that this wouldn&#39;t cause any proble=
ms long-term?<br>
<br>
An alternative solution would be to extract the docscrape source from the n=
umpydoc repo in a vendoring script in SciPy. While okay, that still leaves =
us having to track commits by hand instead of using e.g. a git submodule, a=
nd isn&#39;t robust to upstream changes of directory structure.<br>
<br>
Feedback appreciated! Eric Larson responded on the PR asking whether SciPy =
can introduce a dependency on numpydoc, but that is all so far.<br>
<br>
Cheers,<br>
Lucas<br>
_______________________________________________<br>
NumPy-Discussion mailing list -- <a href=3D"mailto:numpy-discussion@python.=
org" target=3D"_blank">[email protected]</a><br>
To unsubscribe send an email to <a href=3D"mailto:numpy-discussion-leave@py=
thon.org" target=3D"_blank">[email protected]</a><br>
<a href=3D"https://mail.python.org/mailman3//lists/numpy-discussion.python.=
org" rel=3D"noreferrer" target=3D"_blank">https://mail.python.org/mailman3/=
/lists/numpy-discussion.python.org</a><br>
Member address: <a href=3D"mailto:[email protected]" target=3D"_blank">r=
[email protected]</a><br>
</blockquote></div>

--000000000000c07959064fe69ed1--

--===============8356093133322123338==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

_______________________________________________
NumPy-Discussion mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/numpy-discussion.python.org
Member address: [email protected]

--===============8356093133322123338==--