search

kedro-org / kedro

Kedro is a toolbox for production-ready data science. It uses software engineering best practices to help you create data engineering and data science pipelines that are reproducible, maintainable, and modular.
https://kedro.org
Apache License 2.0
9.46k stars 875 forks source link

Improve reference documentation for the CLI #2604

Open astrojuanlu opened 1 year ago

astrojuanlu commented 1 year ago

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/

image

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

ankatiyar commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

@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?

astrojuanlu commented 1 year ago

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 commented 8 months ago

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

astrojuanlu commented 8 months ago

@Gundalai-Batkhuu https://github.com/kedro-org/kedro/issues/2287#issuecomment-1772379988

stichbury commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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 🙏