Python 3: Restore developer documentation

[LeonarddeR]

Having the ability to run scons on Python 3 made us demolish the ability to create Python source code developer documentation temporarily. This is because epydoc isn't supported on Python 3.

[LeonarddeR]

I've looked into using Sphinx. Some things I found:

• Python, wxPython, PySerial and ConfigObj also use Sphinx
• It is an advised tool by readthedocs
• Installing it from pip requires some additional dependencies. It couldn't be expected from us that we bundle these all in git submodules. We could consider an additional binary repository, tough. I think this is preferred when we decide to use sphinx for more than just the developer documentation.
• It uses RestructuredText as the main code style. It has support for markdown, though only using an extra package. RestructuredText has other benefits over markdown, such as keywords and tables in the default spec.
• It supports type hints with an additional extension
• There is extensive documentation, many products use it.
• For our developer guide, it would be possible to link from the dev guide to module/class/function documentation.

In the current situation, we're using epytext/epydoc style doc strings. These are not compatible with sphinx by default. There is an additional module for this, which I haven't yet tested. I'm not convinced that this is the right direction though. May be we should convert everything to rst/sphinx native style. This shouldn't be very difficult. See this article about a possible migration strategy. There's also the Pyment which I've tested quickly, but that tool doesn't replace the L{link} style markup from epydoc and tends to replace tabs with spaces.

[LeonarddeR]

See also #3255, cross posting there.

In my sphinx branch I created a prototype:

1. Install sphinx using pip: pip3 install sphinx
2. In the mentioned branch, navigate to the devDocs directory
3. Execute make html
4. Consult the _build folder for the output.

Note that the doc string annotations are still epydoc style. This is also a reason for many warnings. However, I've been able to get rid of all tracebacks at source code parsing time.

Cc @feerrenrut

[LeonarddeR]

Investigation update.

After some more tests, it really looks like pyment has too much bugs to continue with it. It introduces empty lines, touches part of function bodies it really should leave alone, etc.
On the other hand, the approach with sed misses the fact that sphinx requires a blank line between the doc string body and the parameter definitions. I wonder whether we could automate this somehow.

[LeonarddeR]

I created a gist that contains prototype code to convert doc strings to sphinx style using regex.

https://gist.github.com/leonardder/82564a57a1a79a36fad79c1b92771c29