Write Monte Carlo interface documentation

[cschwan]

After talking to @scarlehoff I get the feeling that our documentation can be improved in quite a few places. Specifically, we should at least

• improve the documentation that explains what lumis are, how they are related to partonic channels and what factors are. We should also add a more complicated example, maybe add the remaining DY LO channels?
• also point out how the lumis are constructed for DIS, which initial state has a hadron and which one doesn't;
• we should better explain the order parameters, for instance the log exponents needed for scale variations, ideally also with an example. An important point is how to decompose the expressions that can be filled into subgrids: alphas not included, alpha must be included and logs must not be included in the log subgrids, but they must be included in the central grid;
• we should also explain all subgrid parameters, which with the CAPI are set using the pineappl_grid_set_{string,double,...} functions. Also explain the basics of interpolation
• explain how to select different subgrid types, which may at some point becomes necessary when memory is a problem
• in Grid::fill and also in other functions/methods we should make clear that whenever we have to give indices for order, bin and lumi that are given in exactly this order, to resemble the obl subcommand of pineappl;
• At the end of the photon-photon DY example program we should add a note that points out using a PDF set with a non-zero photon PDF, otherwise the cross section is zero
• document the recognized metadata and its value format.

[alecandido]

• in Grid::fill and also in other functions/methods we should make clear that whenever we have to give indices for order, bin and lumi that are given in exactly this order, to resemble the obl subcommand of pineappl;

Just as a feedback, and with no further purpose: I actually find this order a bit unnatural, since for me bin is the most external object, the one surviving all the convolutions.
I would have found more natural bol sorting, but at this point that's it, and it's not worth to switch.

[felixhekhorn]

I can try to help with this, but let me repeat what I said in #130 (comment)

• 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

@alecandido can you please remind me of the Rust project you showed to me where the documentation was as source code and hence on docs.rs?

[alecandido]

It is simple, it's just ndarray. You can find examples here:

https://github.com/rust-ndarray/ndarray/tree/master/src/doc

But I'd actually improve over this: instead of docs.rs containing markdown, I'd make docs.md, and docs.rs embed the content of docs.md through a macro.

[alecandido]

Something like this:

https://doc.rust-lang.org/std/macro.include_str.html

[cschwan]

Something that I now feel quite comfortable with is to host common mark documents in the repository and point to it (on github) in the --help documentation of pineappl. For instance, for pineappl remap --help I removed the text that explained REMAPPING, which now points to https://github.com/N3PDF/pineappl/blob/master/docs/cli-reference.md, which has the same text. There I also explain a few other things that are quite handy.

[felixhekhorn]

Maybe you want a README in https://github.com/N3PDF/pineappl/tree/master/docs ?

[alecandido]

A README.md (but even README, README.txt, and README.rst) would be rendered by GitHub in the folder view, like for the top-level one.
So, I agree with @felixhekhorn

[cschwan]

That's probably a good idea. Right now there's the top-level README which points to the various documents, but it might better to have it close to the other documents.

[cschwan]

@aykhuss you might be interested in some of the items in #141 (comment).