README for developers on FINUFFT documentation.

The .rst files in this directory are designed for sphinx to auto-generate
documentation in HTML (including from the readthedocs.io website), and in PDF.

The main procedure to regenerate the documentation from source is
``make docs`` from the top-level directory. See ``../makefile`` for
what's going on here. This does some custom bash scripts for the various
language interface docs, then uses sphinx to make latex and html
versions of the entire manual. The readthedocs.io website is triggered
to update when github master branch changes. The idea is:

*.docsrc ---(bash)---> *.doc ----(included in)----> *.rst -----(sphinx)-->

/  PDF (sits in the repo)
\  HTML ---(readthedocs trigger)--->   finufft.readthedocs.io

Do not edit files ``docs/*.doc`` since these are machine-generated; your changes will be overwritten. Instead edit files ``*.docsrc`` once you have understood how the bash scripts act on them.

There are also separate MATLAB/Octave (bash) and Python (autodoc) doc
generations going on.

To perform doc-generation, you need to set up the following environment
(we have only ever done this on linux):

python3
sphinx  - (at least v1.3), can conda install. Needs latex and latexmk
          (for ubuntu 20.04: sudo apt install texlive-base latexmk)
texext  - a small sphinx helper for math, seems only to be pip-installable:
          https://github.com/matthew-brett/texext

Then to check the local build of the HTML docs, useful for debugging before you
wait for a git push origin to be detected by RTD, point your browser to the
local file _build/html/index.html

finufft.readthedocs.io should have been set up to be triggered by
pushes to the git repo to regenerate HTML documentation identical to the
local copy, hosted there for the world to see.

Note that ../README.md also should be considered part of the docs, since
it contains a precis for text-loving and github-facing humans.

