Guides Build Status / docs job does not catch warnings as errors

[pdurbin]

If you look at pull request #8106 you'll see "all checks have passed" including the one for docs:

However, if you get on the branch locally and run make html the build fails:

This means that the GitHub action for docs is giving us a false sense of security. It's saying the docs are ok, but they won't actually build.

Interestingly, we do see the warnings in the pull request:

So maybe we need to treat the warnings as errors in the docs GitHub Action, like we do in the Makefile? This is with SPHINXOPTS = -W

(venv) HMDC-beamish:sphinx-guides pdurbin$ sphinx-build --help | grep W -B6
  Console output options:
    -v                increase verbosity (can be repeated)
    -q                no output on stdout, just warnings on stderr
    -Q                no output at all, not even warnings
    -N                do not emit colored output
    -w FILE           write warnings (and errors) to given file
    -W                turn warnings into errors

[donsizemore]

It looks like you're using Sphinx 1.5.6. The Jenkins nodes and the GitHub Actions workflow are using 3.5.4, which currently builds cleanly on develop:

$ sphinx-build -b html -d build/doctrees -W source build/html
Running Sphinx v3.5.4
loading translations [en]... done
making output directory... done
loading intersphinx inventory from http://docs.python.org/objects.inv...
intersphinx inventory has moved: http://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 100 source files that are out of date
updating environment: [new config] 100 added, 0 changed, 0 removed
reading sources... [100%] versions                                                                                                                                                                                                                 
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] versions                                                                                                                                                                                                                  
generating indices... genindex done
writing additional pages... search done
copying images... [100%] user/img/file-search-facets.png                                                                                                                                                                                           
copying downloadable files... [100%] _static/Dataverse_brand_icon.svg                                                                                                                                                                              
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build/html.

Let me know if upgrading Sphinx doesn't clear things up?

[pdurbin]

I upgraded to 3.5.4 locally but I get the same error:

(venv) HMDC-beamish:sphinx-guides pdurbin$ make html
sphinx-build -b html -d build/doctrees  -W source build/html
Running Sphinx v3.5.4
loading translations [en]... done
loading intersphinx inventory from http://docs.python.org/objects.inv...
intersphinx inventory has moved: http://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 100 source files that are out of date
updating environment: [new config] 100 added, 0 changed, 0 removed
reading sources... [100%] versions                                              

Warning, treated as error:
/Users/pdurbin/github/iqss/guides.dataverse.org/doc/sphinx-guides/source/api/native-api.rst:2821:Definition list ends without a blank line; unexpected unindent.
make: *** [html] Error 2
(venv) HMDC-beamish:sphinx-guides pdurbin$ git log --oneline | head -1
21fd6377d Merge branch 'develop' into 41-add-auth-to-harvest-api
(venv) HMDC-beamish:sphinx-guides pdurbin$ 

Please note that I'm on 21fd637 on the 41-add-auth-to-harvest-api branch, not develop.

[pdurbin]

Pull request #8118 was a good fix. Thanks, @donsizemore !

Now when pull requests have docs that don't build (that is, where make html fails), it'll be clear for the author or anyone doing code review. I'll put an example below. See "Guides Build Status / docs (pull_request) Failing after 26s".

[donsizemore]

@pdurbin I did it for the T-shirt.