Use latest Sphinx version and understand builds

[nathanshammah]

As documented in #131 last comments, the build fails with Sphinx 3 (latest major release on Pypi).

There error did read as:

 Test documentation with sphinx2s
##[error]Process completed with exit code 2.
Run cd docs && sphinx-build -b html source build
Running Sphinx v3.0.2
loading translations [Python]... not available for built-in messages

Exception occurred:
  File "/opt/hostedtoolcache/Python/3.7.6/x64/lib/python3.7/site-packages/sphinx/application.py", line 1069, in add_source_parser
    self.registry.add_source_parser(*args, **kwargs)
TypeError: add_source_parser() takes 2 positional arguments but 3 were given
The full traceback has been saved in /tmp/sphinx-err-xbd5y7ct.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
##[error]Process completed with exit code 2.

It seems related to this issue between the latest sphinx release and m2r (I was on sphinx 2 while I set the requirements to the latest pypi version, 3).

All this stuff occurred in order to include markdown files outside of the source directory.

I avoided the issue by pinning to sphinx v.2. We could switch back to recommonmark, by using symlinks in the include, e.g. ln -s ../README.md. This is advisable as m2r is not under active development.

[nathanshammah]

Minor comment on paths

sphinx-build -b html source build and make html have different outcomes. The first command creates the html files directly in docs/build, the second one in docs/build/html. However, setting sphinx-build -b html source build/html is not exactly the same, as make html generates also the additional docs/build/toctree folder. This may be ok and we can check with readthedocs once we'll host the docs online.

This is just something to keep in mind, when the conf.py file is not changed: doing make html just changes files in docs/build/html/ and one should check those files. This is also why sometimes I found html files seemingly not updated (due to this path confusion).

Minor comment on make html vs. sphinx-build html ...

make html, like make doctest is a simple way to call the sphinx-build <build-option> ... with a make file, which is generated by sphinx-quickstart. So basically the alternatives are sphinx-quickstart (only the first time the documentation is generated) + make ..., or the explicit sphinx-build .... There is some redundancy in how this is explained in the readme-docs and how it is set up on CI. It's very harmful but it looks redundant, cutting the sphinx-build ... would be fine, since the make.bat is now in the master already (I generated it with sphinx-quickstart the first time).

Minor comment on pdf output

Regarding make latexpdf, it creates another folder, build/latex. The import of the svg badges via the http fails (Warning), but it is due to the fact that the repository is private. But it is also true that it fails to include svg files (Error). This is something to check once the directory is public.

It takes me two latex builds to generate the TOC, I'm not sure if it is because of the errors (skip all with button "s" or just as usual double-build in latex, as for references).

The file now has quite a few white pages in different sections, it would be nice to cut it down.