Adding In-repository Documentation

[playonverbs]

This PR adds Sphinx-based documentation to the repository coupled with a GitHub actions workflow that builds a documentation site on new commits to the main branch.

Currently the documentation is a foundation for others to build upon by adding their own example workflows. There are also a few necessary additions needed to complete the documentation:

Important

The major parts currently missing from the documentation are:

• Executables
  • univmake
  • Unfolder
• Configuration Files (everything after file_properties.txt
• Writing your own selection
  • The main text on writing your own selection.
  • Details on the fields of AnalysisEvent (can be removed in lieu of the table in Liang's examples)

Dependencies

A few auxiliary dependencies have been added when it comes to locally building this documentation to preview your own changes. These are:

• The uv python version manager. This in combination with the pyproject.toml file defines all other python package dependencies that uv will install in a virtual environment.

Building

Locally (for previewing)

After uv has been installed, run uv sync in the directory to install all dependencies. Two options are available for building the documentation:

• To build the documentation once, run: make -C docs/ dirhtml, then serve the directory with uv run python -m http.server -d docs/build/dirhtml. Open the indicated address with your web browser to preview the site.
• To build the documentation on any file changes, run: uv run sphinx-autobuild docs/source docs/build/html/ --port 1313. View the given address to see the site that is rebuilt as you edit the files.

Building on GitHub

Important

GitHub Pages must be enabled for this repository for the Workflow to work properly.

The .github/workflows/docs.yml file defines a GitHub workflow that should build the documentation from the repo and upload the generated site to GitHub Pages. This is triggered to run when a commit has been pushed to main, so no additional work should be required. If you'd like the documentation to be built when a different condition is met (like when a new tag is pushed), that is also possible.

Advice on Contributing

Generally

This documentation is written in reStructuredText (rST). A quick primer for it is available on the Sphinx-doc site and should account for most use-cases. rST can be a bit pedantic about syntax, so checking the output of the local build command is a good idea.

Example-Specific

Each contributed example workflow can be added in docs/source/examples, in a standalone .rst file. In your example file you can add the following snippet to indicate your contribution on that page:

Example Title
=============

.. sectionauthor:: Your Name

.. your page content