Merge pull request #1829 from CEED/jeremy/documentation-markers

Use HTML comments as doc inclusion markers

doc - use HTML comments as inclusion markers

doc - hide inclusion markers in md

Merge pull request #703 from CEED/jed/doc-myst-nb

doc: replace recommonmark with MyST

doc: replace recommonmark with MyST and migrate ReST to MyST

This offers more familiar syntax for most writing, as well as natural
$\pi$ math (versus :math:`\pi`) and markdown syntax for all ReST
fe

doc: replace recommonmark with MyST and migrate ReST to MyST

This offers more familiar syntax for most writing, as well as natural
$\pi$ math (versus :math:`\pi`) and markdown syntax for all ReST
features.

The API doc stubs remain in ReST as recommended for autodoc.

https://myst-parser.readthedocs.io/en/latest/sphinx/use.html#use-sphinx-ext-autodoc-in-markdown-files

The change was largely implemented using
https://github.com/executablebooks/rst-to-myst/ with some manual
fix-ups. Tables (both ReST built-in tables and list-table) remain under
eval-rst until they can be manually updated.

show more ...

Merge pull request #487 from CEED/jed/python-packaging

Jed/python packaging

doc: update instructions for Python

Merge pull request #446 from CEED/user-manual

Sphinx user manual published at libceed.readthedocs.io

doc: convert to Sphinx documentation at libceed.readthedocs.io

Some technical notes about the expanded docs/process:

* Doxygen is now restricted to API documentation. Sphinx docs are
incomplete

doc: convert to Sphinx documentation at libceed.readthedocs.io

Some technical notes about the expanded docs/process:

* Doxygen is now restricted to API documentation. Sphinx docs are
incomplete surrogates due to not hyperlinking code listings, though
we hope the Doxygen site can be removed eventually.

* PDF output uses XeTeX (unicode and OTF fonts) with TeX Gyre Pagella
and DejaVu Sans Mono. You may need to install these fonts in order
to build the PDF users manual.

* Obtaining the author list from Git has not worked on
ReadTheDocs (`git shortlog` is empty even though `git log` is not),
so we automatically generate it on developer machines with `make
doc`. If the author information is incorrect/mangled, edit .mailmap
to fix the mapping.

* Math semantics are based on the description here
https://github.com/sphinx-doc/sphinx/issues/3785

Sphinx chooses one of two setups for the maths.

* If there is a single equation, then we wrap the maths in
\begin{equation*} (or equation).

* If there are multiple equations (as determined by the presence of
an empty line), then we wrap the maths first in \begin{aligned}
and then in \begin{align*} (or align).

Co-authored-by: Jeremy L. Thompson <jeremy.thompson@colorado.edu>
Co-authored-by: Jed Brown <jed@jedbrown.org>

show more ...