Re: Split docscrape out from numpydoc
Lucas Colley via NumPy-Discussion <[email protected]> Mon, 20 Apr 2026 20:52:27 +0100
| Newsgroups | gmane.comp.python.numeric.general |
|---|---|
| Message-ID | <[email protected]> |
--===============0676015007930967342== Content-Type: multipart/alternative; boundary=Apple-Mail-3C91D1FB-058D-4578-AD1D-1E229210A890 Content-Transfer-Encoding: 7bit --Apple-Mail-3C91D1FB-058D-4578-AD1D-1E229210A890 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable <html class=3D"apple-mail-supports-explicit-dark-mode"><head><meta http-equi= v=3D"content-type" content=3D"text/html; charset=3Dutf-8"></head><body dir=3D= "auto"><div dir=3D"ltr"></div><div dir=3D"ltr"><div dir=3D"ltr" style=3D"-we= bkit-text-size-adjust: auto;">Hi Ross,</div><div dir=3D"ltr" style=3D"-webki= t-text-size-adjust: auto;"><br></div><div dir=3D"ltr" style=3D"-webkit-text-= size-adjust: auto;">That sounds great! I=E2=80=99m still not sure if SciPy w= ill want to add a runtime dependency on numpydoc, since we only have `numpy`= at the minute=E2=80=A6 but this is at least a step in the right direction!<= /div><div dir=3D"ltr" style=3D"-webkit-text-size-adjust: auto;"><br></div><d= iv dir=3D"ltr" style=3D"-webkit-text-size-adjust: auto;">Might it still make= sense to split docscrape out into a separate repo after your work is done, o= r do you see those as two orthogonal efforts?</div><div dir=3D"ltr" style=3D= "-webkit-text-size-adjust: auto;"><br></div><div dir=3D"ltr" style=3D"-webki= t-text-size-adjust: auto;">Cheers,</div><div dir=3D"ltr" style=3D"-webkit-te= xt-size-adjust: auto;">Lucas</div></div><div dir=3D"ltr"><br><blockquote typ= e=3D"cite">On 20 Apr 2026, at 17:16, Ross Barnowski <[email protected]&= gt; wrote:<br><br></blockquote></div><blockquote type=3D"cite"><div dir=3D"l= tr">=EF=BB=BF<div dir=3D"ltr"><div>Hi Lucas,</div><div><br></div><div>Indeed= I think this is a good idea - SciPy is not the only project that depends (o= r would like to have depended) on the NumpyDocString and docscrape functiona= lity without pulling in Sphinx (or any other dependency).</div><div><br></di= v><div>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](<a href=3D"https://github.com/numpy/numpydoc/pull/651">https:/= /github.com/numpy/numpydoc/pull/651</a>). There are a few final integration t= ests (see checkboxes in the top post in the PR) that I'd like to run to buil= d confidence that the solution works for everyone. That should include repla= cing the vendored code in scipy.</div><div><br></div><div>Does this solution= work for scipy? </div></div><br><div class=3D"gmail_quote gmail_quote_= container"><div dir=3D"ltr" class=3D"gmail_attr">On Mon, Apr 20, 2026 at 5:0= 6=E2=80=AFAM Lucas Colley via NumPy-Discussion <<a href=3D"mailto:numpy-d= [email protected]">[email protected]</a>> wrote:<br></div><b= lockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-lef= t: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 hr= ef=3D"https://github.com/numpy/numpydoc/issues/619" rel=3D"noreferrer" targe= t=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 some= docstrings for the public API. Copying source code like this is never great= given that the two copies can fall out of sync. Vendoring the entire numpyd= oc repo in SciPy, however, or adding numpydoc as a runtime dependency, seem o= ff the table, making the situation worse rather than better.<br> <br> A better solution seems to be to have docscrape be a standalone project, whi= ch SciPy can vendor more easily, and which numpydoc can either depend on or v= endor. =46rom a modularity perspective at least this seems ideal =E2=80=94 t= here are use-cases where you want docscrape, but not numpydoc, available at r= untime. Joren suggested that I float this idea on the mailing list, given th= at he just submitted a patch to the copy in SciPy without realising that it w= as vendored code =F0=9F=98=84.<br> <br> 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 restructuring the rep= os, and a little more if we decide to distribute docscrape as a standalone p= roject, but my hope would be that this wouldn't cause any problems long-term= ?<br> <br> An alternative solution would be to extract the docscrape source from the nu= mpydoc 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, and i= sn't robust to upstream changes of directory structure.<br> <br> Feedback appreciated! Eric Larson responded on the PR asking whether SciPy c= an 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:[email protected]= rg" target=3D"_blank">[email protected]</a><br> To unsubscribe send an email to <a href=3D"mailto:numpy-discussion-leave@pyt= hon.org" target=3D"_blank">[email protected]</a><br> <a href=3D"https://mail.python.org/mailman3//lists/numpy-discussion.python.o= rg" rel=3D"noreferrer" target=3D"_blank">https://mail.python.org/mailman3//l= ists/numpy-discussion.python.org</a><br> Member address: <a href=3D"mailto:[email protected]" target=3D"_blank">ro= [email protected]</a><br> </blockquote></div> </div></blockquote></body></html>= --Apple-Mail-3C91D1FB-058D-4578-AD1D-1E229210A890-- --===============0676015007930967342== 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] --===============0676015007930967342==--