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

datalad.api docstring should be populated with the description of available "commands" #2718

Closed
yarikoptic opened this issue Jul 31, 2018 · 5 comments · Fixed by #2728
Closed

datalad.api docstring should be populated with the description of available "commands" #2718

yarikoptic opened this issue Jul 31, 2018 · 5 comments · Fixed by #2728
Assignees
@kyleam
Labels
documentation Documentation-related issue
Milestone
Release 0.10.3

Comments

@yarikoptic
Copy link
Member

What is the problem?

datalad --help provides a nice list of commands to use, but neither datalad nor datalad.api docstring give any hints on what is available and how should be used. I think they should

  • get a better generic description, possibly mimicking what is presented by datalad --help
  • get the docstring populated with description of the commands (which do get imported while importing .api)
@yarikoptic yarikoptic added the documentation Documentation-related issue label Jul 31, 2018
@yarikoptic-gitmate
Copy link
Collaborator

GitMate.io thinks possibly related issues are #2063 (ENH: datalad shell command), #2693 (datalad aliases), #1193 (datalad mv), #537 (provide API command "credentials"), and #168 (Online index of available collections (datalad.org)).

@kyleam
Copy link
Contributor

kyleam commented Aug 1, 2018

datalad --help provides a nice list of commands to use, but neither datalad nor datalad.api docstring give any hints on what is available and how should be used. I think they should

  • get a better generic description, possibly mimicking what is presented by datalad --help

I'm not sure what you mean by a "generic" description, so I'll assume you're referring to the one-line command summaries shown by datalad --help.

  • get the docstring populated with description of the commands (which do get imported while importing .api)

In my view, trying to dynamically modify datalad{,.api}.__doc__ introduces unnecessary complexity. I'd propose to

  • Add a function print_help or print_commands (or something else?) to datalad.api that will print something similar to what get_description_with_cmd_summary generates for datalad --help. We should be able to pull out common bits from datalad.cmdline.main.

    Running help(datalad.api) or datalad.api? or pydoc datalad.api would then show that function and its docstring, making it easily discoverable.

  • In datalad.__doc__, point to datalad.api as the Python entry-point for datalad.

@yarikoptic
Copy link
Member Author

I'll assume you're referring to the one-line command summaries shown by datalad --help.

yes!

introduces unnecessary complexity

may be for us, but not for the user. Adding a non conventional function to api would add the complexity for user... I typically appreciate just being able to ? things in ipython session and get good docs. E.g. try numpy?. And since we are already loading all the modules/functions there should be little to no run-time impact to adjust the __doc__.

In datalad.__doc__, point to datalad.api as the Python entry-point for datalad.

yes, please

@kyleam
Copy link
Contributor

kyleam commented Aug 2, 2018

may be for us, but not for the user.

Yes, I'm considering the effect on the user in my opinion of whether the complexity is worth it. Again, I don't think it is.

@kyleam
Copy link
Contributor

kyleam commented Aug 2, 2018

Never mind, I was stupidly thinking of the read-only docstrings of classes. Modifying a module-level __doc__ shouldn't add any complexity.

@yarikoptic yarikoptic added this to the Release 0.10.3 milestone Aug 2, 2018
kyleam added a commit to kyleam/datalad that referenced this issue Aug 2, 2018
@kyleam
DOC: Add summary of commands to datalad.api.__doc__
e5e021e 
Make it easier for users to discover what methods are available by
looking at the help for the api module.  One concern with this change
could be that we're bringing in more modules than before, but
inspecting sys.modules suggests that this is not the case.

There is still some code duplication between api._command_summary and
main.setup_parser that could pulled out, but that can be done later if
someone thinks it's worth the effort.

Closes datalad#2718.
kyleam added a commit to kyleam/datalad that referenced this issue Aug 2, 2018
@kyleam
DOC: Tell datalad.__doc__ readers how to see a list of commands
373852a 
Re: datalad#2718
@kyleam kyleam mentioned this issue Aug 2, 2018
Merged
1 task
kyleam added a commit to kyleam/datalad that referenced this issue Aug 2, 2018
@kyleam
DOC: Add summary of commands to datalad.api.__doc__
bdbaca1 
Make it easier for users to discover what methods are available by
looking at the help for the api module.  One concern with this change
could be that we're bringing in more modules than before, but
inspecting sys.modules suggests that this is not the case.

There is still some code duplication between api._command_summary and
main.setup_parser that could pulled out, but that can be done later if
someone thinks it's worth the effort.

Closes datalad#2718.
kyleam added a commit to kyleam/datalad that referenced this issue Aug 2, 2018
@kyleam
DOC: Tell datalad.__doc__ readers how to see a list of commands
84278f4 
Re: datalad#2718
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@kyleam kyleam

Labels
documentation Documentation-related issue
Projects
None yet
Milestone
Release 0.10.3
Development

Successfully merging a pull request may close this issue.

DOC: Add command summaries to datalad.api.__doc__ kyleam/datalad
3 participants
@yarikoptic @kyleam @yarikoptic-gitmate