[documentation] #3509: Generate Kagami CLI help as Markdown #3510

0x009922 · 2023-05-22T01:16:20Z

Description

Self-explanatory PR title.

Linked issue

Closes #3509

Benefits

Same documentation (from doccomments) for both CLI and GitHub.

Checklist

Self-review
Merge [feature] #2373: kagami swarm #3475
Doc review
Initial code review
Fix comments
Re-review
Decide whether we should proceed with clap-markdown or with a self-made tool
Create a follow-up issue: generate kagami help in CI

Signed-off-by: Dmitry Balashov <[email protected]>

0x009922 · 2023-05-22T04:44:58Z

tools/kagami/CLI.md

I don't like the format that clap-markdown produces for a couple of reasons:

Mix of ## and #####

Using bold in headers: ##### **Options:**

Inconsistent spacing

↴ character

Not critical though

Also, it ignores additional text in arguments doccomments and only includes the first line.

What do you mean by this? From what I see, the doccomments are included in full (e.g. for genesis or crypto). Or did you mean that it doesn't preserve formatting without the verbatim attribute?

@ilchu, see: #3510 (comment)

Signed-off-by: Dmitry Balashov <[email protected]>

0x009922 · 2023-05-24T05:39:04Z

It is not much code to write a better docgen implementation. It might be used for other CLIs as well.

ilchu · 2023-05-30T14:04:04Z

tools/kagami/CLI.md

What do you mean by this? From what I see, the doccomments are included in full (e.g. for genesis or crypto). Or did you mean that it doesn't preserve formatting without the verbatim attribute?

ilchu · 2023-05-30T14:05:12Z

tools/kagami/CLI.md

+* `client` — 
+* `peer` — 


Would be good to have short descriptions here as well. Could be done by carrying over the old examples directly into the Args::Config docstring, just like you did with Args::Genesis, I suppose.

ilchu · 2023-05-30T14:09:00Z

tools/kagami/CLI.md

Also would prefer some different title, as either the old README.md or maybe kagami.md sound more descriptive to me. And maybe have this markdown generation a part of our CI, just like e.g. schema is (could be a separate small PR though).

It definitely should be a part of CI.

ilchu · 2023-05-30T14:19:07Z

tools/kagami/CLI.md

+## `kagami tokens`
+
+Generate a list of predefined permission tokens and their parameters
+
+**Usage:** `kagami tokens`


The comment about Args::Config also applies here, despite this part being insubstantial. Even though it's just two small and obvious examples there, I don't think we lose much by omitting them, but being more explicit never hurts.

tools/kagami/src/main.rs

ilchu · 2023-05-30T14:22:28Z

It is not much code to write a better docgen implementation. It might be used for other CLIs as well.

Been thinking about this too, you mean ditching the whole Documented trait and doing something similar for config endpoint docs?

0x009922 · 2023-05-30T22:29:10Z

It is not much code to write a better docgen implementation. It might be used for other CLIs as well.

Been thinking about this too, you mean ditching the whole Documented trait and doing something similar for config endpoint docs?

@ilchu,

Hmm, as far as I understand you are speaking about Iroha configuration documentation, which is generated by kagami docs. I am speaking not about it. (Although you are welcome to put your thoughts here: #3507)

Here I mean that clap-markdown implementation is not complex, and we can write our own clap-based markdown generator (e.g. iroha_clap_markdown crate), with a format that we consider a better option.

0x009922 · 2023-05-30T22:33:05Z

tools/kagami/CLI.md

+* `--image <IMAGE>` — Use specified docker image
+* `--build <PATH>` — Use local path location of the Iroha source code to build images from
+* `--build-from-github` — Clone `hyperledger/iroha` repo from the revision Kagami is built itself, and use the cloned source code to build images from
+* `-p`, `--peers <PEERS>` — How many peers to generate within the docker-compose
+* `--outdir <OUTDIR>` — Target directory where to place generated files
+* `--outdir-force` — Re-create the target directory if it already exists
+* `--no-default-configuration` — Do not create default configuration in the `<outdir>/config` directory
+* `-s`, `--seed <SEED>` — Might be useful for deterministic key generation


Here is the example of that clap-markdown doesn't render additional documentation for arguments. Even if I put #[clap(verbatim_doc_comment)].

For example, --no-default-configuration's full documentation is as follows:

Do not create default configuration in the <outdir>/config directory.

Default config.json, genesis.json and validator.wasm are generated and put into
the <outdir>/config directory. That directory is specified in the Docker Compose
volumes field.

If you don't need the defaults, you could set this flag. The config directory will be
created anyway, but you should put the necessary configuration there by yourself.

Ah, now I see it, thanks. So it doesn't recurse into the submodules args fully. That should be trivially fixable with a home-brew implementation (and sounds really close to what Documented does already anyways).

0x009922 · 2023-05-30T22:37:13Z

tools/kagami/CLI.md

It definitely should be a part of CI.

Signed-off-by: Dmitry Balashov <[email protected]>

Co-authored-by: Ilia Churin <[email protected]> Signed-off-by: 0x009922 <[email protected]>

…into 3509-kagami-clap-markdown # Conflicts: # tools/kagami/src/main.rs

ilchu · 2023-05-31T05:17:13Z

@ilchu,

Hmm, as far as I understand you are speaking about Iroha configuration documentation, which is generated by kagami docs. I am speaking not about it. (Although you are welcome to put your thoughts here: #3507)

That's indeed what I was talking about. Then I'll see if I actually can come up with anything actionable up there!

QuentinI · 2023-05-31T06:52:36Z

I'm a bit bothered that running subcommands with --help (e.g. kagami crypto --help) will output a wall of raw Markdown. I'm not sure the longer docs is even useful there as opposed to keeping it in documentation only; and of course unprocessed Markdown looks quite jarring in a help message

0x009922 · 2023-06-06T08:19:18Z

I'm a bit bothered that running subcommands with --help (e.g. kagami crypto --help) will output a wall of raw Markdown. I'm not sure the longer docs is even useful there as opposed to keeping it in documentation only; and of course unprocessed Markdown looks quite jarring in a help message

I agree. It would be nice to be able to affect how clap prints help messages in CLI, and it might be not difficult to make markdown nicer in that mode. AFAIK clap doesn't provide an API for it.

So, maybe the whole PR is pointless and we should not try combining help message with README docs? Or avoid Markdown in docstrings? But it is a standard for docstrings to be Markdown, so it seems more reasonable to support it from the clap side.

6r1d · 2023-06-06T10:08:35Z

To summarize our recent conversation, I like the format for the generated docs. Thank you for the detailed demo with Asciinema.

0x009922 · 2023-06-08T01:44:37Z

See: #3509 (comment)

0x009922 added 2 commits May 22, 2023 10:10

[docs]: generate CLI.md

181645a

Signed-off-by: Dmitry Balashov <[email protected]>

Merge branch '2373-swarm' into 3509-kagami-clap-markdown

f3fef33

Signed-off-by: Dmitry Balashov <[email protected]>

0x009922 added Enhancement New feature or request iroha2-dev The re-implementation of a BFT hyperledger in RUST Documentation Documentation changes labels May 22, 2023

0x009922 self-assigned this May 22, 2023

0x009922 mentioned this pull request May 22, 2023

[feature] #2373: kagami swarm #3475

Merged

5 tasks

0x009922 commented May 22, 2023

View reviewed changes

Merge branch '2373-swarm' into 3509-kagami-clap-markdown

83b9c01

Signed-off-by: Dmitry Balashov <[email protected]>

appetrosyan requested a review from outoftardis May 30, 2023 08:23

appetrosyan assigned outoftardis May 30, 2023

ilchu suggested changes May 30, 2023

View reviewed changes

0x009922 commented May 30, 2023

View reviewed changes

0x009922 and others added 4 commits May 31, 2023 07:40

Merge branch '2373-swarm' into 3509-kagami-clap-markdown

78bccf1

Signed-off-by: Dmitry Balashov <[email protected]>

[docs]: extend CLI documentation, rename to kagami-help.md

545d38b

Signed-off-by: Dmitry Balashov <[email protected]>

Update tools/kagami/src/main.rs

4c761ae

Co-authored-by: Ilia Churin <[email protected]> Signed-off-by: 0x009922 <[email protected]>

Merge remote-tracking branch 'hyperledger/3509-kagami-clap-markdown' …

c100754

…into 3509-kagami-clap-markdown # Conflicts: # tools/kagami/src/main.rs

QuentinI self-assigned this May 31, 2023

appetrosyan approved these changes Jun 2, 2023

View reviewed changes

0x009922 mentioned this pull request Jun 8, 2023

[documentation] Auto-generate Kagami docs from clap #3509

Closed

0x009922 closed this Jun 8, 2023

nxsaken deleted the 3509-kagami-clap-markdown branch May 28, 2024 06:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[documentation] #3509: Generate Kagami CLI help as Markdown #3510

[documentation] #3509: Generate Kagami CLI help as Markdown #3510

0x009922 commented May 22, 2023 •

edited

Loading

0x009922 May 22, 2023

0x009922 May 22, 2023

ilchu May 30, 2023

0x009922 May 30, 2023

0x009922 commented May 24, 2023

ilchu May 30, 2023

ilchu May 30, 2023

ilchu May 30, 2023

0x009922 May 30, 2023

ilchu May 30, 2023

ilchu commented May 30, 2023

0x009922 commented May 30, 2023

0x009922 May 30, 2023

ilchu May 31, 2023

0x009922 May 30, 2023

ilchu commented May 31, 2023

QuentinI commented May 31, 2023

0x009922 commented Jun 6, 2023

6r1d commented Jun 6, 2023

0x009922 commented Jun 8, 2023

[documentation] #3509: Generate Kagami CLI help as Markdown #3510

[documentation] #3509: Generate Kagami CLI help as Markdown #3510

Conversation

0x009922 commented May 22, 2023 • edited Loading

Description

Linked issue

Benefits

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

0x009922 commented May 24, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ilchu commented May 30, 2023

0x009922 commented May 30, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ilchu commented May 31, 2023

QuentinI commented May 31, 2023

0x009922 commented Jun 6, 2023

6r1d commented Jun 6, 2023

0x009922 commented Jun 8, 2023

0x009922 commented May 22, 2023 •

edited

Loading