write documentation

[lukasheinrich]

in yadage, we have a travis deploy job that automatically builds docs and pushes to gh-pages

https://github.com/diana-hep/yadage/blob/master/.travis.yml#L25

• [x] Setup CI
• [x] Add automodule in order to get source docs
• [x] Setup theme that supports Google Style docstrings

[matthewfeickert]

@lukasheinrich I don't know how much of a hassle it would be to change Sphinx themes, but I think it would be really nice if we could adopt a Sphinx theme that allowed for Google Style docstrings. To my mind they are much more readable while looking at the actual code, which is a plus.

As an example, PyTorch uses them with the Read The Docs Sphinx theme. So their docstrings (like this one for torch.distributions.bernoulli) end up looking like this when rendered.

If this sounds feasible it looks like we could either use sphinx_rtd_theme or napoleon. Thoughts?

[lukasheinrich]

ok so a stub is live here: http://diana-hep.github.io/pyhf now we just need to fill it with some content my editing the files under docs/source

[matthewfeickert]

@lukasheinrich Great! Cool to see the start of the docs!

[matthewfeickert]

but I think it would be really nice if we could adopt a Sphinx theme that allowed for Google Style docstrings.

Based off of @kratsg's comment in PR #157

This isn't theme-dependent. That's just a functionality baked into Sphinx itself.

This should be possible.

[kratsg]

I'll add an example of this in the PR so it's there to work off of.

[kratsg]

I'll add an example of this in the PR so it's there to work off of. done

[kratsg]

This should be up and running http://diana-hep.org/pyhf/. This issue can be closed as it mostly represents "setting up documentation", rather than writing it? #38 seems related as well.

[matthewfeickert]

Closing this given the above.