Sphinx remaining warnings and CI check

[sergisiso]

The 3 Sphinx projects are almost warning-free now. The remaining warnings are: developer guide: /home/sergi/workspace/stfc/PSyclone/doc/developer_guide/developers_gocean1p0_stencils.rst: WARNING: document isn't included in any toctree reference guide:

/home/sergi/workspace/stfc/PSyclone/src/psyclone/psyir/symbols/__init__.py:docstring of psyclone.psyir.symbols.TYPE_MAP_TO_PYTHON:3: WARNING: Unexpected indentation.
/home/sergi/workspace/stfc/PSyclone/src/psyclone/psyir/symbols/__init__.py:docstring of psyclone.psyir.symbols.TYPE_MAP_TO_PYTHON:4: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/sergi/workspace/stfc/PSyclone/src/psyclone/psyir/symbols/__init__.py:docstring of psyclone.psyir.symbols.TYPE_MAP_TO_PYTHON:7: WARNING: Unexpected indentation.
/home/sergi/workspace/stfc/PSyclone/src/psyclone/psyir/symbols/__init__.py:docstring of psyclone.psyir.symbols.TYPE_MAP_TO_PYTHON:9: WARNING: Inline strong start-string without end-string.

If we would clean those we could set a CI task with make html SPHINXOPTS="-W" to automatically mark when a new issues is introduced. It is something I often miss to check before finishing my PRs.

@rupertford @arporter @hiker @TeranIvy What do you think?

[sergisiso]

In my latest documentation changes I tried to fix this problem, now CI will do:

- run: cd doc/user_guide; make html SPHINXOPTS="-W --keep-going"
- run: cd doc/developer_guide; make html SPHINXOPTS="-W --keep-going"
- run: cd doc/reference_guide; make html
- run: cd doc/psyad/user_guide; make html SPHINXOPTS="-W --keep-going"

To report Warnings as Errors (and fail the CI)

However, I will not close the issue because the remaining ref_guide warnings, tracked in #1793 and #1280

And because l SPHINXOPTS also supports a "-n" (nitpicking) flag that when enabled reports many issues in each documentation, and we should consider if these are worth fixing and enabling in the CI as well