Improve reference documentation for the CLI

[astrojuanlu]

Description

It would be nice to have reference documentation for the CLI in a more visible place.

Context

At the moment, the only way for a user to know what options exist for a given kedro subcommand is to run it with -h locally.

There is an incomplete CLI reference https://docs.kedro.org/en/stable/development/commands_reference.html but it's under the wrong section, and it doesn't document all the possible options.

The functions powering the CLI are partially documented, but not fully, and browsing them is not very ergonomic anyway: https://docs.kedro.org/en/stable/kedro.framework.cli.html

Possible Implementation

https://sphinx-click.readthedocs.io/

Possible Alternatives

Depending on how long it takes us to get to this issue and the outcome of gh-2072, we might want to use https://github.com/DataDog/mkdocs-click instead (glad to see Sphinx doesn't have the monopoly in this aspect)

Relevant Ticket

• Improve the error message & docstring of kedro new for custom starters #2618

[ankatiyar]

@astrojuanlu We do have this - https://docs.kedro.org/en/stable/development/commands_reference.html Right now it's under Advanced Usage -> Development -> Kedro's Command Line Interface. Maybe we need to make it more visible?

[astrojuanlu]

OMG thanks @ankatiyar, I totally missed that.

Definitely having it under Advanced Usage -> Development is not the right place.

On the other hand, I don't consider that a full reference because there are some options missing. For example, I don't see --starter for kedro new mentioned there.

But definitely it's better than nothing, we could start by moving it.

[noklam]

@astrojuanlu I think it's still valuable to have some plugin to generate CLI doc automatically. I am trying to improve some documentation in our plugins, do you think we need docs for our plugins as well?

• Provide more helpful message for kedro airflow create -h kedro-plugins#244

[astrojuanlu]

do you think we need docs for our plugins as well?

Absolutely yes! I have some ideas on how we can dramatically improve the situation of our multi-repo docs, but I'm waiting for the user research process @stichbury is leading to end to take them.

[Gundalai-Batkhuu]

Hi all. Is it okay if I start working on this documentation?

[astrojuanlu]

@Gundalai-Batkhuu #2287 (comment)

[stichbury]

Hi @Gundalai-Batkhuu how are you? Today is the last day of October so please do slip any final PRs into our queue for Hacktoberfest if you have them ready?

[Gundalai-Batkhuu]

Hi. I'm still working on a couple of tickets. I don't have PR's now for the hacktoberfest. But I'd like to continue contributing to the project. I've been using Kedro for couple of years so I want to give back

[stichbury]

That's awesome, thank you @Gundalai-Batkhuu -- just wanted to make sure we had time set aside if you needed review for Hacktoberfest. We'll gladly contributions whenever you are ready in the coming weeks 🙏