docs: add cli docs

[yathomasi]

From comment

How do we go about docs for these commands? Let's please review and created tickets if needed.

Do we mean sth like this ?

Putting as draft as we need to include all the commands before we merge.

[cloudflare-workers-and-pages]

Deploying datachain-documentation with    Cloudflare Pages

Latest commit:	2b7cb70
Status:	✅  Deploy successful!
Preview URL:	https://a39b6a90.datachain-documentation.pages.dev
Branch Preview URL:	https://add-cli-docs.datachain-documentation.pages.dev

View logs

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 87.65%. Comparing base (e455180) to head (2b7cb70).
Report is 28 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #577      +/-   ##
==========================================
- Coverage   87.83%   87.65%   -0.19%     
==========================================
  Files         100      106       +6     
  Lines        9993    10292     +299     
  Branches     1356     1386      +30     
==========================================
+ Hits         8777     9021     +244     
- Misses        873      929      +56     
+ Partials      343      342       -1     

Flag	Coverage Δ
datachain	87.59% <100.00%> (-0.18%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[shcheklein]

Do we mean sth like this ?

No. It looks like Python API docs to me. It should be more like what we have in dvc.org for CLI. I'm not sure if there are good example for this engine.

[yathomasi]

I see mkdocs support for cli autodocs with mkdocs-click extension i.e for cli using click. But, for us, I see we use argparse.

@iterative/datachain I see we lack proper restructuring for cli commands. So, could you please check the feasibility of using click for proper structure? Also, we can generate the docs using mkdocs-click.

If we don't want to take that road, we should basically follow the same procedure as we do for dvc.org i.e write them manually for all the commands.

[shcheklein]

So, could you please check the feasibility of using click for proper structure

tbh, I don't like click. To my mind it doesn't provide enough value for an extra dependency, standard lib gives 95% of what we need. Also, click is breaking some basic (to my mind) things. E.g. there is no way you could append -v at the end of the command to debug it (you have to put in the right position, somewhere in between all args).

If we don't want to take that road, we should basically follow the same procedure as we do for dvc.org i.e write them manually for all the commands.

@skshetry what is your take on this?

[yathomasi]

I could only find way to autodoc generation with mkdocs for cli commands is using mkdocs-click or mkdocs-typer of which we don't use both. (plugins list)

It would be great if there was a solution. If not I don't see alternative of doing them manually.

cc: @iterative/datachain @shcheklein

[shcheklein]

I guess it's fine to do it manually, since we don't need it to be in two places anyway (vs API call descriptions / docs), right?

I'm not that familiar with mkdocs tbh to make the decision.

[0x2b3bfa0]

Maybe someone is crazy enough to prototype¹ mkdocs-argparse during a planning session at 6 a.m., don't you think? 😈

Footnotes

1. Still missing a few important things: deduplication of global command-line options, tests... ↩

[0x2b3bfa0]

Given that there's already mkdocs-typer and typer is such a nice library, maybe it's an option worth considering as well.

[0x2b3bfa0]

Writing high-quality documentation by hand and maintaining it is also a good option, but it's a lot of work.