Unify CLIs

[stefmolin]

Changes:

• Created numpydoc entry point (replacing the hook's entry point).
• Moved CLI logic out of __main__.py and into a dedicated cli.py file.
• Refactored the CLI to use subparsers and treat each of the unique functionalities as a subcommand like git: render, validate, and lint.
• Updated test_main.py for changes and addition of lint option.
• Removed the -m option from the hook, so that usage is now from numpydoc lint.
• Updated the entry point for the pre-commit hook to numpydoc lint.
• Updated validation docs.
• Updated the test.yml workflow, but I didn't add a corresponding lint command as I don't fully understand what that part does.

Closes #467

[jarrodmillman]

Thanks!!

[jarrodmillman]

Stefan is back and will take a look at this soon. He is a little backlogged. Thanks for your patience.

[stefanv]

Thank you very much @stefmolin.

I see that I get a traceback when no import path is specified.

I think I suggested the numpydoc being an alias for numpydoc render before (bad Stéfan!), and now realize it is rather confusing. Perhaps we should let numpydoc (without arguments) print help? Or, at minimum, print a proper error message when import_path is None.

[stefanv]

Looks good, I think the lint subparser perhaps needs to be hooked up more cleanly, but tested everything locally and it works. Thank you again!

[stefanv]

Can we clarify here the distinction between validate and lint. They do the same, except the one operates on a function and the other on a file? But validate doesn't allow disabling certain rules, which confused me.

[stefmolin]

I think it works for non-functions as well. How about this?

Validate an object's docstring conforms to the numpydoc standard.

[stefmolin]

I'm not sure what to do about the second part of your comment. If you run numpydoc validate --help you see what can be passed as arguments, and there aren't any for disabling rules.

[stefanv]

"Validate that an object's docstring conforms to the numpydoc standard" (added "that")

[stefanv]

Or, "Determine (or check?) whether an object's docstring..."

[stefanv]

Otherwise just: "Validate an object's docstring against the numpydoc standard"

[stefanv]

I may prefer the last version, but anything gramatically sound is fine.

[stefanv]

I'm not sure what to do about the second part of your comment. If you run numpydoc validate --help you see what can be passed as arguments, and there aren't any for disabling rules.

This was more of a question: should there be the option of disabling certain rules? Why are these not exactly equivalent in their functionality?

[stefmolin]

I'm not sure what to do about the second part of your comment. If you run numpydoc validate --help you see what can be passed as arguments, and there aren't any for disabling rules.

This was more of a question: should there be the option of disabling certain rules? Why are these not exactly equivalent in their functionality?

While I agree this should eventually be the case, this definitely seems out of scope for this PR. At least the separate subcommands will not draw attention to arguments that have no effect like before (see #459).

[stefanv]

Thanks @stefmolin! The new interface is great.

[stefanv]

@rossbar @jarrodmillman handing it over to you.