Project documentation

[gipert]

I'm posting a to-do list here. I'll keep it up-to-date. Good reference: https://scikit-hep.org/developer

• Regenerate API documentation automatically at build time
• Fix all warning/errors reported by Sphinx and add missing docstrings. Read the contribution guide (refactor branch). Add @gipert as a reviewer for your pull requests. Assignments (put your name!):
  • dsp @iguinn
  • flow
  • hit @wisecg
  • lgdo @jasondet
  • math
  • pargen @ggmarshall
  • raw @jasondet
  • vis @iguinn
• Include more general guides (eg how to run the full chain) separate pages. @gipert, ...
• Let one CI job fail if there are Sphinx errors/warnings: https://github.com/marketplace/actions/sphinx-build
• Complete contribution guide
• Create pull request template on GitHub that references the contribution guide
• Implement logic to make https://legend-exp.github.io/pygama/index.html redirect to the latest stable tag done on readthedocs.io
• Automatically embed Jupyter notebooks in website. Requires the data to be publicly available on https://github.com/legend-exp/legend-testdata
• Move tutorials to docs/?
• Alllow for automatic reference to external documentation: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
• Support reStructuredText and Markdown
• [long-term] build documentation on main only? not needed on readthedocs.io