Write a tutorial for the PineAPPL CLI

[cschwan]

At the moment the only documentation of the CLI is in the CLI itself, using

pineappl --help

or similarly for each subcommand, for instance for convolute:

pineappl convolute --help

While this is okay for an experienced user, we need a short tutorial which

• categorizes and
• explains the different subcommands - as of writing this there are 18 (!) of them - and
• showcases each of them. Finally we should
• explain our terminology, for instance what do we call a grid, a subgrid, an FK table, what is 'obl', etc.

[alecandido]

You can put it as:

• a separate subcommand: pineappl tutorial, but
• my favorite way would be to use the docstrings themselves, and publish as crate docs (that are available offline for a cargo installation, and online on https://docs.rs without any installation at all)

Nothing prevents to do both, but I'd start from the second.

[cschwan]

The first option is an interesting idea! The second option isn't possible right now, as docs.rs doesn't document binaries. Have a look at https://docs.rs/crate/pineappl_cli/0.5.1. I was thinking of simply writing markdown documents in the git repository, which is simple and works quite well.

[alecandido]

Ok, that's bad... but it is what it is.

Then, what you can do is to write simple markdown documents, and compile them into the tutorial subcommand with something like include_str!.
Finally, you can use something like termimad to print them.

[felixhekhorn]

why not use #116 ?

[alecandido]

why not use #116 ?

Three reasons for me:

1. no offline version would be provided that way
2. at the moment it's just a presentation/gallery, this would add a second purpose to that page, calling for a more sophisticated architecture for it
3. and it's by itself more sophisticated than markdown files (in order to write it offline and test, you need to use jekyll, that is written in Ruby and needs Ruby installed)

I'd say it's way more complicated. Markdown files are easy to write, and the further subcommand is something more you can add (an extension), but they do not depend on it.
Docstrings would have been more integrated with the code itself, and it's machinery that is already part of Cargo, but unfortunately it's not an option...

[cschwan]

Commit 352be79 adds a first part of the tutorial.

[cschwan]

@alecandido @felixhekhorn @scarlehoff I've completed a first version of the tutorial, if you like you can have a look at it and let me know if there's anything that can be improved or missing. The tutorial is now in docs/cli-tutorial.md (read it online).

[felixhekhorn]

I think it's a good start! maybe a few comments:

• why did you choose an example with a typo? 🙃
• in the lumi representation: can't we cast 0 -> 21?
• since it's quite long: maybe add a table of contents?
• it remains unclear to me what is your maintained source of documentation: repo (meaning this file), inline (meaning pineappl tutorial), docs (on docs.rs), website

[cschwan]

@felixhekhorn thanks for your comments! I will definitely replace the grid with an updated version, where the typo is fixed, where gluons have PDG ID 21 and most importantly where the missing factor 0.5 is taken care of; I added it before this bug was fixed. I chose this grid simply because it was already there for unit tests.

A table of contents is a very good idea, I will add it. For the time being the tutorial must be viewed either in the repository or rendered on github, and we should probably link it on the new website. As far as I understand docs.rs doesn't document binaries, but I have to read the corresponding Issue, maybe I can workaround it: rust-lang/docs.rs#238.

[alecandido]

• since it's quite long: maybe add a table of contents?

I perfectly agree that if it's the final form, a table of contents is useful in general. However, for the specific case of reading it on GitHub, the table of contents is already present (click top right corner), and even searchable:

[alecandido]

I finally took the time to read it: it's really enjoyable and descriptive.

I believe this is really the correct size for the tutorial: you can read in 10-20 minutes (according to the personal experience with the topic) and it gives you an idea of the most important concepts, including a taste of the power and flexibility of the CLI.

I would not expand beyond this size, it's perfect.
If ever you want to add more topics, I would do it as separate "advanced" tutorials on specific tasks (but in that case you have the CLI help, so I believe there is much less need for them).

[cschwan]

• since it's quite long: maybe add a table of contents?

I perfectly agree that if it's the final form, a table of contents is useful in general. However, for the specific case of reading it on GitHub, the table of contents is already present (click top right corner), and even searchable:

Huh, I didn't know that, that's useful.

I finally took the time to read it: it's really enjoyable and descriptive.

I believe this is really the correct size for the tutorial: you can read in 10-20 minutes (according to the personal experience with the topic) and it gives you an idea of the most important concepts, including a taste of the power and flexibility of the CLI.

Cheers, that's hight praise!

I would not expand beyond this size, it's perfect. If ever you want to add more topics, I would do it as separate "advanced" tutorials on specific tasks (but in that case you have the CLI help, so I believe there is much less need for them).

That was also my idea, there are some hidden features that are really cool and I'd like to show them. One problem of the CLI help is that it's quite condensed and therefore it has a discoverability problem. As you say an advanced tutorial would fill this gap.

[scarlehoff]

Is it possible to add a man page in a cargo project? Having this tutorial as part of man pineappl minus plots would be cool.

[alecandido]

Is it possible to add a man page in a cargo project? Having this tutorial as part of man pineappl minus plots would be cool.

I believe this to be a long-standing issue, see rust-lang/cargo#2729.

[cschwan]

But there is some development in clap, which I use for the CLI: https://github.com/clap-rs/clap/tree/master/clap_mangen. I'll have a look at it because I also like manpages a lot.

[cschwan]

I believe the tutorial is mostly there. For manpages I've opened a separate Issue: #145.