Flesh out base documentation with introduction/background/details

[kratsg]

Description

This PR fleshes out our documentation so it is a little less bare-bones and gives people things to read and understand the history/background behind the project.

Checklist Before Requesting Reviewer

• Tests are passing
• "WIP" removed from the title of the pull request
• Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

• Summarize commit messages into a comprehensive review of the PR

* Add background information on HistFactory
* Detail some of the mathematical formulation used in pyhf
* Add schema discussion in more detail

[lukasheinrich]

do we have a way to preview the docs of a PR? I guess not but it might be useful (not sure if there is such a functionality in RTD)

[kratsg]

do we have a way to preview the docs of a PR? I guess not but it might be useful (not sure if there is such a functionality in RTD)

could develop staging with GH actions.

[matthewfeickert]

could develop staging with GH actions.

Can you elaborate? You're saying have some sort of separate deploy area for visual inspection? Or am I totally lost?

[kratsg]

Can you elaborate? You're saying have some sort of separate deploy area for visual inspection? Or am I totally lost?

Basically, GH actions should let you deploy to some website on every PR (or at least, say, trigger some integratoin/webhook) and master is built with GH-pages.

[kratsg]

https://pyhf-staging.readthedocs.io/en/docs-pubdate/

[coveralls]

Coverage remained the same at 93.67% when pulling 2d1b1a5 on docs/pubdate into 14f4b31 on master.

[matthewfeickert]

@kratsg First, the docs you made are freaking amazing. Really nice! 😃 I have 4 questions though:

1. Do you know how we can get the left LaTeX quotes to render correctly around "auxiliary measurements"?

``auxiliary measurement''

Doesn't work
2. Can you remind @lukasheinrich and me how you are actually getting https://pyhf-staging.readthedocs.io/en/docs-pubdate/ deployed? I don't see an added file in the PR that does this, so did you just set it up to watch? We're both just curious.
3. At the moment the text is split across lines as it wraps over around 80 spaces. Do you have any objection to me making it 1 sentence per line (now that you've done the hard work)?
4. You had brought up using netlify. Do you have any further thoughts on that here?

[kratsg]

1. It's fixed now (see https://mathhelpboards.com/math-formulas-mathjax-62/rh-lh-double-quotes-mathjax-1511.html). Note that this isn't latex, but MathJax.

2. You can set up a RTD build without setting up the webhook. It just means you're doing (manual) p(o|u)lling instead of triggers.

3. We don't do that in the rest of the documentation. If there's no black equivalent here, I'd like to leave it as it is.

4. It would be nice to set it up if I had permissions to change the settings of this project... @lukasheinrich ?

[kratsg]

Builds can be (re)started manually here: https://readthedocs.org/projects/pyhf-staging/builds/

[matthewfeickert]

2. We don't do that in the rest of the documentation. If there's no black equivalent here, I'd like to leave it as it is.

Hm. I hadn't noticed this as I've mostly been writing docstrings with one sentence per line. (I've noticed there are some edge cases in which this matters, but I don't have an example I can point you to.)

Would you be open to the idea of at least starting a new line after each sentence? This makes it easier for me to focus on the sentence as an atomic chunck (but I also have softwrap on).

[kratsg]

Would you be open to the idea of at least starting a new line after each sentence? This makes it easier for me to focus on the sentence as an atomic chunck (but I also have softwrap on).

Ok, but we really only have this week to get the docs out. We're on a short timeline.

[matthewfeickert]

Thanks. LGTM. Let's approve this and get it merged in.

We can discuss linebreaks and things later.