Unify cli validation interfaces

[Stefan van der Walt]

See #454

python -m numpydoc
python -m numpydoc.hooks.validate_docstrings

These CLI interfaces do slightly different things, but one could imagine a command word interface a-la git.

Also, it would be good to expose this as an executable user-script numpydoc.

/cc @stefmolin

[Stefanie Molin]

I'll tackle this one after #466

[Stefanie Molin]

Is there a preference between these two options?

$ numpydoc render           # runs the current numpydoc CLI's render_object()
$ numpydoc validate         # runs the current --validate
$ numpydoc validate --ast   # runs the current numpydoc.hooks.validate_docstrings

OR to not affect current users:

$ numpydoc                    # runs the current numpydoc CLI's render_object()
$ numpydoc --validate         # runs the current --validate
$ numpydoc --ast-validation   # runs the current numpydoc.hooks.validate_docstrings

I'm calling the hook method "ast" because it uses the abstract syntax tree unlike the original validation, but let me know if we should use something else.

[Stefan van der Walt]

How about:

$ numpydoc  # alias for numpydoc render
$ numpydoc render
$ numpydoc validate

[Stefanie Molin]

And numpydoc validate would have the flag to trigger the hook version?

[Stefan van der Walt]

Or just drop the alias; it's not like this is done so often by hand.

[Stefanie Molin]

Looking at this more, I actually don't think the --validate logic should be combined with the hook logic because they operate on different inputs: the hook takes files and the --validate option takes a dotted path, which could be to anything.

How about having separate subcommands for each?

$ numpydoc render
$ numpydoc validate
$ numpydoc hook

[Stefan van der Walt]

Nice and clean; I prefer that too.

[Stefan van der Walt]

hook is perhaps not a super intuitive name; numpydoc lint?