Docs: Enable API documentation on RTD

Use `breathe` to generate documentation and link to user and developer
manual.

doc/manual/requirements.txt

@@ -1,3 +1,7 @@
 # Extra packages required for building documentation on ReadTheDocs
 
+sphinx
+Pygments
+sphinx-rtd-theme
+readthedocs-sphinx-ext
 breathe

doc/manual/source/conf.py

@@ -26,12 +26,16 @@
 
 # Are we running this on ReadTheDocs
 on_rtd = os.environ.get("READTHEDOCS") == 'True'
+
+# Only build API docs if the user specifically requests it. On RTD we build it
+# all the time
 use_breathe = tags.has("use_breathe") or on_rtd
 
 if on_rtd:
     try:
-        subprocess.call("cd ../../doxygen; doxygen Doxyfile.rtd")
+        subprocess.call("cd ../../doxygen; doxygen Doxyfile.rtd", shell=True)
     except:
+        # Gracefully bailout if doxygen encounters errors
         use_breathe = False
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -192,3 +196,4 @@ def setup(app):
                         indextemplate="pair: %s; CMake configuration")
 
     app.add_config_value("use_breathe", use_breathe, 'env')
+    app.add_config_value("on_rtd", on_rtd, 'env')

doc/manual/source/dev/apidocs.rst

@@ -1,12 +1,17 @@
 NaluWindUtils API Documentation
 ===============================
 
-.. ifconfig:: not use_breathe
+.. ifconfig:: not use_breathe and not on_rtd
 
    API documentation requires Doxygen and Breathe, a Doxygen-Sphinx
    documentation linking package. Please install these packages and regenerate
    documentation if you wish to browse C++ source code documentation via Sphinx.
 
+.. ifconfig:: not use_breathe and on_rtd
+
+   An error occurred when attempting to generate C++ documentation using
+   Doxygen. Please visit later or file a bug report with the developers.
+
 .. ifconfig:: use_breathe
 
    .. toctree::