Merge pull request #482 from CEED/leila/doc_NS

Leila/doc ns

doc: switch from mathjax to katex

Merge pull request #469 from CEED/jed/doc-examples

Jed/doc examples

doc: split examples into separate files in the source tree

* Copy examples/**.rst into the source directory so they can be picked
up by Sphinx.
* Some minor corrections/clarifications to docs that

doc: split examples into separate files in the source tree

* Copy examples/**.rst into the source directory so they can be picked
up by Sphinx.
* Some minor corrections/clarifications to docs that I noticed while
splitting them apart (shame on me for bundling in this commit).

show more ...

Merge pull request #446 from CEED/user-manual

Sphinx user manual published at libceed.readthedocs.io

doc: process restrict qualifier as predefined

Breathe and/or Sphinx lacks support for restrict qualifiers, so use
the workaround suggested here to hide the restrict qualifier from
Breathe/Sphinx.

h

doc: process restrict qualifier as predefined

Breathe and/or Sphinx lacks support for restrict qualifiers, so use
the workaround suggested here to hide the restrict qualifier from
Breathe/Sphinx.

https://github.com/michaeljones/breathe/issues/477#issuecomment-593145041

An alternative is to use the C domain for *.c and *.h files. This
handles restrict, but reduces enum names to their numeric value. Once
that Breathe/Sphinx bug is fixed, we could skip the restrict elision
in favor of using the C domain.

show more ...

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