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:

sphinx
doxygen
breathe
exhale

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++?
• There are many errors as sphinx attempts to parse existing docstrings. Should those be resolved as part of this PR? E.g.,

pyorbit3/py/orbit/time_dep/time_dep.py:docstring of orbit.time_dep.time_dep.TIME_DEP_Lattice:3: ERROR: Unexpected indentation. [docutils]
pyorbit3/py/orbit/time_dep/time_dep.py:docstring of orbit.time_dep.time_dep.TIME_DEP_Lattice:4: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]

Glimpse of the current configuration:

[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.