Sphinx-generated documentation

[woodtp]

Produce official documentation for PyORBIT. Automatically generates the Python API reference with sphinx.ext.autosummary. To enable automatic documentation for the C++ part of the repo, a combination of Doxygen, Breathe, and Exhale is used.

Important

New dependencies included in a separate docs-environment.yml:

sphinx
doxygen
breathe  # sphinx-doxygen bridge
exhale   # automatic documentation of C++ library API
myst-parser  # markdown support
sphinx-copbutton  # turn on 'copy-to-clipboard' buttons in codeblocks.

Todo

• Quick Start/Installation instructions/examples/other static content
• Figure out why sphinx.ext.autosummary works intermittently between the various orbit modules.
• Extend to C++ portion of code base.
  • Doxygen bridge via breathe
• Setup HTML deployment to somewhere... lab-hosted? GitHub Pages?
  • CI/CD
• Decide on a theme
• Ship dependenciesrequirements.txt required to build docs.
• How to handle documentation of python bindings to C++?

Current state is deployed from this feature branch to the following url:
https://pyorbit-collaboration.github.io/PyORBIT3

[woodtp]

I'm not a fan of how sphinx-apidoc appends each submodule of orbit with "... package" in the header. I think it would be cleaner if each item in the TOC was simply:

orbit.aperture
orbit.bunch_generators
...

I haven't yet determined whether details like these are customizable in the options or would it require manual intervention/an external script.

[woodtp]

Relevant to #84, apparently compilation will fail if any of numpy, scipy, or matplotlib are missing as a consequence of:

PyORBIT3/py/orbit/matching/matching.py

Lines 4 to 9 in 7c67f1c

	from numpy import *
	from scipy.optimize import fsolve
	from scipy.optimize import root
	from scipy.integrate import odeint
	from scipy.constants import c
	from matplotlib.pyplot import *

PyORBIT3/py/orbit/orbit_correction/orbit_correction.py

Lines 10 to 11 in 7c67f1c

	import numpy as np
	from scipy.optimize import leastsq

#101 resolves this.

[woodtp]

Automatic generation of docs for the C++ part of the repo is working with the inclusion of Breathe and Exhale. I'm excluding all of the wrapper code from being documented; we probably want to handle documentation of bindings in a more useful format.

[woodtp]

Reverting cdc67ff and 5f422a4 because increasing the timeout for actions/deploy-pages beyond 10 minutes doesn't do anything.

[woodtp]

Closing this PR and reopening against PyORBIT-Collaboration/PyORBIT3:feature/documentation

edit: see #106