Building the docs using python 3

[Johannes Schönberger]

Hi,

> I've recently tried to make the transition to python3, at least for skimage development and testing. There is one issue stopping me: The documentation of skimage can't be built using python3 (keep in mind that we should also use a version of sphinx based on python3).
> 
> Many of the issues that pop up when using python3 seem to be related to various sphinx extensions, for example scikit-image/doc/ext/numpydoc.py and scikit-image/doc/tools/{apigen.py,build_modref_templates.py}. I've seen several of these files have already been ported to python3 by other projects (numpy and ipython, at least), but I have not searched extensively for these newer versions.
> 
> I assume that we do want the docs to build using python3. The question is how we go about porting the files in question with a minimal duplication of the efforts made by other projects? Just copying files into the skimage source tree seems very much like a short-term solution to me…

I do not see another way than copying the relevant extension files from NumPy. Any other suggestions?

> On a related note, it would be nice to have travis CI build the docs and look for errors automatically. Presently, if an example fails to run, that example seems to simply disappear from the generated docs without the build failing; this is hardly ideal.


Travis currently runs all examples, building the docs as well is a good addition in my opinion.