If module is missing a docstring show readme if available #39093
Conversation
|
It would be nice to open either an editor or a pager if the README is long. |
|
Or, at the very least, show only up to the the first N characters of the README, for a suitable choice of N. |
IanButterworth
force-pushed
the
ib/module_docstring_from_readme
branch
from
f3bdef3 to
fc03a94
Compare
I think figuring out opening another editor/viewer would be hard to get the UX right across all the different front ends
Is the annoyance of having too much text print greater than the possible annoyance of the text being cut off just before the bit you need? Perhaps a line limit makes sense, but I'd make it quite large. Large enough to show the entire example above, at least |
Yeah you can definitely make it really large. |
Could we re-use the functionally of |
Lets leave this for another discussion. For this PR, I think we should just show the whole thing; or with some very loose cap on number of lines like it currently has. |
|
Could this hook into the While docstrings are written with the intention of being used like this, some readme files are pretty long, written assuming you have a browser. |
|
I would rather like to see instead some mechanism to nudge package authors into providing a proper introductory docstring for each module, e.g. by running a test for the presence of such docstrings at package registration, or README.md files could focus on information for people who have not yet downloaded and installed the module, and therefore their content would be somewhat more orthogonal to module docstrings. |
Yeah, module docstrings are best. I don't think it's an either/or though, implementing what you suggest as well as this PR could be a fair way forward |
|
First info now prints on a single line |
|
How would this behave for packages added to custom sysimgs? |
|
Good point. I added handling if |
|
@StefanKarpinski Just a bump for review 🙏🏻 |
|
Updated given exported names are now shown on master if no module docstring exists: compared to 1.6.0 |
IanButterworth
force-pushed
the
ib/module_docstring_from_readme
branch
from
446d9dc to
eaf307d
Compare
IanButterworth
changed the title
…39093) * print available readme if no docstring for module * tweak search & print * handle pathless modules * limit readme print to first 200 lines * review changes * print message on single line * handle modules in sysimage that are missing src files * tweak formatting * fix docstring test
…39093) * print available readme if no docstring for module * tweak search & print * handle pathless modules * limit readme print to first 200 lines * review changes * print message on single line * handle modules in sysimage that are missing src files * tweak formatting * fix docstring test
…39093) * print available readme if no docstring for module * tweak search & print * handle pathless modules * limit readme print to first 200 lines * review changes * print message on single line * handle modules in sysimage that are missing src files * tweak formatting * fix docstring test
(re)enables printing of readme's, if the module is missing a docstring. (supposedly this used to happen in some 0.x versions)
Recursively climbs up the path to the root package directory looking for readmes, in case a specific nested module has a dedicated readme at that directory level.