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
Hello! 👋 #39093 is great! This PR styles the banner ("Displaying contents of readme found at ...") differently: Before: ``` help?> DifferentialEquations search: DifferentialEquations No docstring found for module DifferentialEquations. Exported names ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ @derivatives, @ode_def, @ode_def_all, @ode_def_bare, ... (manually truncated) Displaying contents of readme found at /Users/ian/.julia/packages/DifferentialEquations/HSWeG/README.md ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ DifferentialEquations.jl ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ (Image: Join the chat at https://gitter.im/JuliaDiffEq/Lobby) (https://gitter.im/JuliaDiffEq/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) (Image: Build Status) (https://github.com/SciML/DifferentialEquations.jl/actions?query=workflow%3ACI) (Image: Stable) (http://diffeq.sciml.ai/stable/) (Image: Dev) (http://diffeq.sciml.ai/dev/) (Image: DOI) (https://zenodo.org/badge/latestdoi/58516043) This is a suite for numerically solving differential equations written in Julia and available for use in Julia, Python, and R. The purpose of this package is to supply efficient Julia implementations of solvers for various differential equations. Equations within the realm of this package include: • Discrete equations (function maps, discrete stochastic (Gillespie/Markov) simulations) • Ordinary differential equations (ODEs) ``` After: ``` help?> DifferentialEquations search: DifferentialEquations No docstring found for module DifferentialEquations. Exported names ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ @derivatives, @ode_def, @ode_def_all, @ode_def_bare, ... (manually truncated) ──────────────────────────────────────────────────────────────────────────── Package description from README.md: DifferentialEquations.jl ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ (Image: Join the chat at https://gitter.im/JuliaDiffEq/Lobby) (https://gitter.im/JuliaDiffEq/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) (Image: Build Status) (https://github.com/SciML/DifferentialEquations.jl/actions?query=workflow%3ACI) (Image: Stable) (http://diffeq.sciml.ai/stable/) (Image: Dev) (http://diffeq.sciml.ai/dev/) (Image: DOI) (https://zenodo.org/badge/latestdoi/58516043) This is a suite for numerically solving differential equations written in Julia and available for use in Julia, Python, and R. The purpose of this package is to supply efficient Julia implementations of solvers for various differential equations. Equations within the realm of this package include: • Discrete equations (function maps, discrete stochastic (Gillespie/Markov) simulations) • Ordinary differential equations (ODEs) ``` I think this makes it a bit less technical (the word "Displaying" and the long filename), and it improves the reading flow.
Hello! 👋 #39093 is great! This PR styles the banner ("Displaying contents of readme found at ...") differently: Before: ``` help?> DifferentialEquations search: DifferentialEquations No docstring found for module DifferentialEquations. Exported names ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ @derivatives, @ode_def, @ode_def_all, @ode_def_bare, ... (manually truncated) Displaying contents of readme found at /Users/ian/.julia/packages/DifferentialEquations/HSWeG/README.md ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ DifferentialEquations.jl ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ (Image: Join the chat at https://gitter.im/JuliaDiffEq/Lobby) (https://gitter.im/JuliaDiffEq/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) (Image: Build Status) (https://github.com/SciML/DifferentialEquations.jl/actions?query=workflow%3ACI) (Image: Stable) (http://diffeq.sciml.ai/stable/) (Image: Dev) (http://diffeq.sciml.ai/dev/) (Image: DOI) (https://zenodo.org/badge/latestdoi/58516043) This is a suite for numerically solving differential equations written in Julia and available for use in Julia, Python, and R. The purpose of this package is to supply efficient Julia implementations of solvers for various differential equations. Equations within the realm of this package include: • Discrete equations (function maps, discrete stochastic (Gillespie/Markov) simulations) • Ordinary differential equations (ODEs) ``` After: ``` help?> DifferentialEquations search: DifferentialEquations No docstring found for module DifferentialEquations. Exported names ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ @derivatives, @ode_def, @ode_def_all, @ode_def_bare, ... (manually truncated) ──────────────────────────────────────────────────────────────────────────── Package description from README.md: DifferentialEquations.jl ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡ (Image: Join the chat at https://gitter.im/JuliaDiffEq/Lobby) (https://gitter.im/JuliaDiffEq/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) (Image: Build Status) (https://github.com/SciML/DifferentialEquations.jl/actions?query=workflow%3ACI) (Image: Stable) (http://diffeq.sciml.ai/stable/) (Image: Dev) (http://diffeq.sciml.ai/dev/) (Image: DOI) (https://zenodo.org/badge/latestdoi/58516043) This is a suite for numerically solving differential equations written in Julia and available for use in Julia, Python, and R. The purpose of this package is to supply efficient Julia implementations of solvers for various differential equations. Equations within the realm of this package include: • Discrete equations (function maps, discrete stochastic (Gillespie/Markov) simulations) • Ordinary differential equations (ODEs) ``` I think this makes it a bit less technical (the word "Displaying" and the long filename), and it improves the reading flow.
(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.