Description
One thing I hoped to talk about at the summit but didn't manage to was doccer (SciPy's internal tool for docstring deduplication). MNE-Python adopted/adapted doccer many years ago, and it helped us find and fix many outdated/inaccurate docstrings.
The problem we're facing is that
- the docstrings can't be easily read in the source code.
- the docstrings are only filled in when the package is imported, which means static analyzers like pyright don't fill them in. This means that in vscode the various hover/tooltip/tab-completion things also (like the source files themselves) show the cryptic docstring placeholders instead of the filled-in parameter descriptions
Problem 1 alone wouldn't be so bad (arguably an advantage, as it reduces scrolling past screens and screens of docstring between snatches of actual code), but combined with problem 2 it has left some of our devs in a perpetually frustrated state.
My questions are:
- have SciPy devs found good workarounds to the problems I mention above?
- One solution I already know is "have an ipython terminal open in your IDE, and if you need to read a docstring, use
?(likemne.what.ever?)" but I'm interested in other approaches
- One solution I already know is "have an ipython terminal open in your IDE, and if you need to read a docstring, use
- how are other packages besides SciPy and MNE dealing with param descriptions (or other aspects of docstrings) that are repeated across many parts of your codebase (i.e., how do you keep them in sync)?