Description

The main things to get over our docs troubles happened elsewhere:

• hosting the built html/ through GH pages avoids the / anchors that netlify was dropping into our href links that were in turn confusing the psicode.org redirects (https://github.com/psi4/psicode-hugo-website/blob/master/netlify.toml#L14) and making links seem broken for psicode.org/psi4manual .
• the combination of progressing Sphinx development and stagnant cloud theme development (from which the sphinx_psi_theme is derived) eventually robbed us of the "search" bar and the homing logo. That got minimally revived through psi4/sphinx-psi-theme@feda211 , so use the v1.1 now.

But there's a few modest improvements here, especially to allow anyone so inspired to switch the docs theme and figure out new customizations. Apart from a certain fondness for the colors and an insistence that tables like https://psicode.org/psi4manual/master/introduction.html#id59 not be mangled, I'd be pleased if anyone wanted to overhaul the docs theme. Some things to know:

• psi4 colors and specializations are https://github.com/psi4/sphinx-psi-theme/blob/master/sphinx_psi_theme/themes/sphinx_psi_theme/theme.conf#L37
• to use a different theme, pass -DSPHINX_THEME=another_theme to cmake (or edit it in the cache)
• build with cmake --build . --target sphinxman
• built docs will be in <objdir>/doc/sphinxman/html/. that html dir can be tarred and sent anywhere to load in a browser.

Dev notes & details

• the two sphinx extensions that were in the sphinx_psi_theme are now stored here in the repo. this lets them be used by any theme, which is important for the QCVariables one that otherwise emits thousands of warnings.
• more logic around @SPHINX_THEME@ in the controlling docs/sphinxman/source/conf.py.in so that one can use options and configuration particular to different themes. feel free to add more. tried themes are psi, cloud, basic, furo, and pydata. beware that some modern themes take a looong time to build (e.g., 40m instead of 5m) and increase the docs size 10-fold. at least one culprit is trying to put the whole TOC in the sidebar (incl. 1400 options), so there's stuff to be solved to try to transition themes.
• I thought https://sphinx-tabs.readthedocs.io/en/latest/ would be a nice way to show psithon/psiapi/qcschema syntax, so I added that requirement to the docs build along with a quick example.

Checklist

• Tests added for any new features
• All or relevant fraction of full tests run

Status

• Ready for review
• Ready for merge