Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

inherit documentation of args and kwargs from sub-functions #22

Closed
lukashergt opened this issue Jul 11, 2019 · 3 comments
Closed

inherit documentation of args and kwargs from sub-functions #22

lukashergt opened this issue Jul 11, 2019 · 3 comments
Labels
discussion docs Documentation upgrades enhancement New feature or request

Comments

@lukashergt
Copy link
Collaborator

Could docrep be potentially of interest for inheriting documentation of parameters from one function to another?

This could be the solution to avoiding copy-pasting of docs and to "good docs are better than no docs, but no docs are better than bad docs".

Example of a use-case:
Currently samples.plot_1d's docstring only informs about one argument: axes. It might be helpful for the user to also see arguments going into samples.plot, though. In particular the plot_type argument which is documented in plot would be useful to know about in plot_1d.
@lukashergt lukashergt added enhancement New feature or request discussion labels Jul 11, 2019
@williamjameshandley
Copy link
Collaborator

This does sound pretty good. It looks like it should be compatible with our sphinx rtd implementation too, since we follow numpy conventions.

  1. Are you able to submit a minor PR with an example of it in action for a subsection of the code?
  2. Are there any other similar packages? How do numpy, scipy or matplotlib implement their nested documentation?

lukashergt pushed a commit to lukashergt/anesthetic that referenced this issue Jul 11, 2019
example of docrep applied to samples.plot and samples.plot_1d
7333e36 
* This addresses issue handley-lab#22 and provides an example of `docrep` in
  action:
  - `docrep` gets the parameters from the docstring of `samples.plot`
    and appends them to the parameters section in the docstring of
    `samples.plot_1d`.

* `docrep` added to requirements.txt and requirements_minimal.txt for
  this.
@lukashergt lukashergt mentioned this issue Jul 11, 2019
Closed
5 tasks
@lukashergt
Copy link
Collaborator Author

  1. done

  2. matplotlib does some docstring interpolation but the documentation on how to do it is rather opaque.

@williamjameshandley williamjameshandley added this to the 1.2 milestone Jul 12, 2019
@williamjameshandley williamjameshandley modified the milestones: 1.2, 1.3 Aug 24, 2019
@williamjameshandley williamjameshandley mentioned this issue Aug 26, 2019
Merged
5 tasks
@williamjameshandley williamjameshandley removed this from the 1.3 milestone Jan 22, 2020
@lukashergt lukashergt mentioned this issue Aug 20, 2020
Merged
5 tasks
@williamjameshandley williamjameshandley mentioned this issue Aug 23, 2020
Merged
5 tasks
@lukashergt lukashergt mentioned this issue Jul 13, 2022
Merged
5 tasks
This was referenced Oct 13, 2022
Merged
Open
@williamjameshandley williamjameshandley added the docs Documentation upgrades label Apr 5, 2023
@williamjameshandley
Copy link
Collaborator

partially resolved by #239

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
discussion docs Documentation upgrades enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@williamjameshandley @lukashergt