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 never great given that the two copies can fall out of sync. Vendoring the entire 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 — 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, given that he just submitted a patch to the copy in SciPy without realising that it was vendored code 😄. 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 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 leaves 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 SciPy 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]
