Turn Sphinx warnings into errors in CI (#2754)

.github/workflows/docs-test.yml

@@ -9,6 +9,10 @@ on:
     branches:
       - development
 
+env:
+  # enable color output from Sphinx
+  FORCE_COLOR: "1"
+
 jobs:
   docs:
     runs-on: ubuntu-latest
@@ -33,7 +37,10 @@ jobs:
       - name: Build docs
         run: |
           cd Docs/
-          make SPHINXOPTS=-v NO_DOXYGEN=TRUE html
+          # remove missing TOC entries that would otherwise be generated by
+          # doxygen to avoid warnings about missing references
+          sed -i -e 's/^   filelist$//; s/^   classlist$//' source/index.rst
+          make SPHINXOPTS='-v -W --keep-going' NO_DOXYGEN=TRUE html
 
       - name: Check links
         run: |

.gitignore

@@ -72,6 +72,8 @@ Docs/source/namespacelist.rst
 Docs/source/runtime_parameters.rst
 Docs/source/*_files.rst
 Docs/source/preprocessed_files
+Docs/source/yt_example.rst
+Docs/source/yt_example_files/
 
 
 amr_diag.out

Docs/rp.py

@@ -7,17 +7,17 @@
 from more_itertools import unique_everseen
 
 MAIN_HEADER = """
-+--------------------------------------------+-------------------------------------------------------------+---------------+
-| parameter                                  | description                                                 | default value |
-+============================================+=============================================================+===============+
++--------------------------------------------+-------------------------------------------------------------+-----------------------------+
+| parameter                                  | description                                                 | default value               |
++============================================+=============================================================+=============================+
 """
 
 SEPARATOR = """
-+--------------------------------------------+-------------------------------------------------------------+---------------+
++--------------------------------------------+-------------------------------------------------------------+-----------------------------+
 """
 
 ENTRY = """
-| {:42} | {:59} | {:13} |
+| {:42} | {:59} | {:27} |
 """
 
 WRAP_LEN = 59

Docs/source/FlowChart.rst

@@ -309,7 +309,7 @@ In the code, the objective is to evolve the state from the old time,
    A. Create ``Sborder``, initialized from ``S_old``
 
    B. Call ``clean_state()`` to make sure the thermodynamics are in
-     sync, in particular, compute the temperature.
+      sync, in particular, compute the temperature.
 
    C. [``SHOCK_VAR``] zero out the shock flag.
 

Docs/source/docutils.conf

@@ -0,0 +1,2 @@
+[parsers]
+line_length_limit = 1000000

Docs/source/index.rst

@@ -60,7 +60,7 @@ https://github.com/amrex-astro/Castro
 
    filelist
    classlist
-   .. namespacelist
+.. namespacelist
 
 .. toctree::
    :caption: References