Closed cschwan closed 2 years ago
You can put it as:
pineappl tutorial
, butcargo
installation, and online on https://docs.rs without any installation at all)Nothing prevents to do both, but I'd start from the second.
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.
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.
why not use #116 ?
why not use https://github.com/N3PDF/pineappl/issues/116 ?
Three reasons for me:
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...
Commit 352be793b0c3f8829a8a57254d3d8384f689adb6 adds a first part of the tutorial.
@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).
I think it's a good start! maybe a few comments:
pineappl tutorial
), docs (on docs.rs), website@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: https://github.com/rust-lang/docs.rs/issues/238.
- 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:
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).
- 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.
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.
Is it possible to add a
man
page in a cargo project? Having this tutorial as part ofman pineappl
minus plots would be cool.
I believe this to be a long-standing issue, see https://github.com/rust-lang/cargo/issues/2729.
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.
I believe the tutorial is mostly there. For manpages I've opened a separate Issue: https://github.com/N3PDF/pineappl/issues/145.
At the moment the only documentation of the CLI is in the CLI itself, using
or similarly for each subcommand, for instance for convolute:
While this is okay for an experienced user, we need a short tutorial which