Fix docs parameter formatting (#318)

* Add ReadTheDocs config file

The ReadTheDocs developers recommend using a configuration file.
When .readthedocs.yaml is present, the 'Advanced settings -> Default settings'
section of the ReadTheDocs admin panel is ignored and the configuration
file is used instead.

The yaml file has some benefits when compared to the web-based
settings panel:

- If you move conf.py or requirements.txt, you can update
  .readthedocs.yaml at the same time. That way, you retain the ability
  to easily rebuild old versions of the docs, because ReadTheDocs will
  automatically use the corresponding settings.

- External contributors can see how we have configured ReadTheDocs,
  which may help them in understanding our project structure with
  respect to documentation.

- There are some settings you can change via the yaml file that you
  cannot change via the web interface.

* Specify version requirements more precisely

The docs for 4.1.0 were rebuilt a few months after release, and they
changed in appearance (for the worse). Examining the build logs, it
seems that the packages used for the build changed from Sphinx-3.5.3
and breathe-4.28.0 to Sphinx-4.0.2 and breathe-4.30.0.

Following the ReadTheDocs advice for Reproducable Builds [1], I'm now
specifying exact versions for our key dependencies.

[1]: https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html

* Turn sphinx warnings into errors

* Specify docutils 0.16

There are conflicts between docutils >=0.17 and our sphinx style,
so use the last working version. This fixes the rendering of lists
in the rocsolver documentation.

* Fix sphinx underline too short warning

.readthedocs.yaml

@@ -0,0 +1,14 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+sphinx:
+   configuration: docs/source/conf.py
+
+formats: all
+
+python:
+   version: "3.7"
+   install:
+   - requirements: docs/source/requirements.txt

docs/run_doc.sh

@@ -11,5 +11,5 @@ bash run_doxygen.sh
 # Build sphinx docs
 cd source
 make clean
-make html
-make latexpdf
+make SPHINXOPTS='-W --keep-going' html
+make SPHINXOPTS='-W --keep-going' latexpdf

docs/source/api_lapacklike.rst

@@ -193,7 +193,7 @@ rocsolver_<type>getri_npvt_outofplace_batched()
 .. doxygenfunction:: rocsolver_sgetri_npvt_outofplace_batched
 
 rocsolver_<type>getri_npvt_outofplace_strided_batched()
------------------------------------------------------
+-------------------------------------------------------
 .. doxygenfunction:: rocsolver_zgetri_npvt_outofplace_strided_batched
    :outline:
 .. doxygenfunction:: rocsolver_cgetri_npvt_outofplace_strided_batched

docs/source/requirements.txt

@@ -1,2 +1,5 @@
-
-breathe
+docutils==0.16
+sphinx==3.5.3
+sphinx_rtd_theme==0.4.3
+readthedocs_sphinx_ext==2.1.4
+breathe==4.28.0