Sphinx-build Action does not fail upon warnings

[FroggyFlox]

This issue arose in https://github.com/rockstor/rockstor-doc/pull/406#issuecomment-1407397318

We should sync our Github action running sphinx-build to our backend doc building and treat warnings as errors so that warnings are easily seen in the Github action summary (would show as failed).

We currently use the following in our backend:

sphinx-build -b html -E -W . _build/html

but in our Github action, we run: https://github.com/rockstor/rockstor-doc/blob/3beeecaeb93b45f33bc60a26d944d7f546336067/.github/workflows/pull-request.yml#L16

... which itself runs:

sphinx-build -b html -d _build/doctress . _build/html

We should thus add the following options: https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-E

-E

Don’t use a saved environment (the structure caching all cross-references), but rebuild it completely. The default is to only read and parse source files that are new or have changed since the last run.

https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-W

-W

Turn warnings into errors. This means that the build stops at the first warning and sphinx-build exits with exit status 1.

@phillxnet , we may want to also use the following, so that we can have a full list of warnings reported the first time rather than rerunning everything until it passes.

https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-keep-going

--keep-going

With -W option, keep going processing when getting warnings to the end of build, and sphinx-build exits with exit status 1.

[FroggyFlox]

Running the proposed command on a branch with 2 underlines shorter than their title (similar to warnings in #406) gives:

$ sphinx-build -b html -E -W --keep-going . _build/html
Running Sphinx v6.1.3
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 72 source files that are out of date
updating environment: [new config] 72 added, 0 changed, 0 removed
reading sources... [100%] ups-setup/ups_setup                                                                                                                                                                                          
/home/FroggyFlox/Documents/PycharmProjects/rockstor-doc/data_loss.rst:4: WARNING: Title underline too short.

Data Loss-prevention and Recovery in Rockstor
==================================
/home/FroggyFlox/Documents/PycharmProjects/rockstor-doc/data_loss.rst:44: WARNING: Title underline too short.

Pool drive count advice
--------------

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] ups-setup/ups_setup                                                                                                                                                                                           
generating indices... genindex done
writing additional pages... search done
copying images... [100%] ups-setup/nut_netclient.png                                                                                                                                                                                   
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
Writing redirects...
build finished with problems, 2 warnings.

The command did return 1:

$ echo $?
1