documentation build fixes for ReadTheDocs

.github/workflows/build.yml

@@ -131,8 +131,8 @@ jobs:
           github_actions_ci/validate-wdl-womtool.sh
 
   ## note: this test_docs job does not actually produce the output on readthedocs
-  ## readthedocs does its own build trigger. this travis job exists simply to alert us
-  ## of build failures of the docs because otherwise we would never know.
+  ## readthedocs does its own build trigger. this job exists simply to 
+  ## attempt a build and alert us of documentation build failures because otherwise we would never know.
   test_docs:
     runs-on: ubuntu-20.04
     steps:

.readthedocs.yml

@@ -7,6 +7,7 @@ version: 2
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
+  builder: html
   configuration: docs/conf.py
 
 # Build documentation with MkDocs
@@ -18,6 +19,6 @@ formats: all
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3.6
+  version: 3.8
   install:
-    - requirements: docs/requirements.txt
+    - requirements: docs/requirements.txt

docs/conf.py

@@ -12,7 +12,6 @@
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
-
 import sys
 import os
 import subprocess
@@ -48,8 +47,21 @@ def _make_wdl_markdowns():
             fname_base = os.path.basename(wf)
             if fname_base.endswith('.wdl'):
                 fname_base = fname_base[:-4]
-                subprocess.check_call(['wdl-aid', '-o', fname_base+'.md', os.path.join(wf_dir, wf)])
-                outf.write("   {}\n".format(fname_base))
+                try:
+                    # generate markdown file for specific wdl
+                    subprocess.run([
+                                        'wdl-aid', 
+                                        '-o', fname_base+'.md', 
+                                        os.path.join(wf_dir, wf)
+                                    ], 
+                                    check=True, 
+                                    stdout=subprocess.PIPE, 
+                                    stderr=subprocess.STDOUT)
+                    # add entry for the wdl to the main markdown file
+                    outf.write("   {}\n".format(fname_base))
+                except subprocess.CalledProcessError as e:
+                    print ( f"Error({e.returncode}):\n{e.output.decode('utf-8')}" )
+                    raise
         outf.write("\n")
 _make_wdl_markdowns()
 
@@ -77,7 +89,7 @@ def _make_wdl_markdowns():
 
 # General information about the project.
 project = 'viral-ngs'
-copyright = '2014, Broad Institute Viral Genomics'
+copyright = '2023, Broad Institute Viral Genomics'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/requirements.txt

@@ -1,7 +1,9 @@
-Sphinx
+jinja2==3.1.2 # https://github.com/readthedocs/readthedocs.org/issues/9037#issuecomment-1077818554
+Sphinx==5.3.0 #override sphinx pinning done by RTD: https://docs.readthedocs.io/en/stable/build-default-versions.html#external-dependencies
 sphinx-argparse
-sphinx_rtd_theme
-PyYAML
-mock
+sphinx-rtd-theme==1.1.1
+PyYAML==6.0
+mock==5.0.1
 recommonmark
-wdl-aid
+miniwdl==1.8.0
+wdl-aid==1.0.0

github_actions_ci/build-docs.sh

@@ -3,5 +3,14 @@
 set -e
 
 pushd docs
-make html && echo "Docs built successfully!" || echo "Docs did NOT build successfully."
+
+make html
+
+build_exit_code=$?
+if [ $build_exit_code -eq 0 ]; then
+    echo "Docs built successfully"
+else
+    echo "Docs did NOT build successfully"
+    exit $build_exit_code
+fi
 popd

github_actions_ci/install-pip-docs.sh

@@ -2,3 +2,6 @@
 
 echo "pip installing test-related packages (Sphinx, etc.)"
 pip install --quiet -r docs/requirements.txt
+
+# list what was installed
+pip freeze