Building the documentation locally

[atoav]

I am trying to build the documentation locally, so I can get a preview of what I am working on. I am just getting familiar with sphinx, so maybe this is my own fault, or some version incompatibility I use:

>>> sphinx.version_info
(1, 6, 7, 'final', 0)

What I tried

• When I run sphinx-build -b html . ../html inside the repo, it complains about a missing conf.py
• When I ignore the conf.py via sphinx-build -C -b html . ../html it complains that there is no contents.rst¹
• I then temporarily added a conf.py with master_doc = 'index' inside, but then he doesn't create the TOC with multiple warnings of the kind: WARNING: document isn't included in any toctree

What I suspect

• I installed sphinx via apt-get python3-sphinx, maybe it is a python3 vs python27 issue?
• Maybe you have a conf.py somewhere that isn't in this repo for some reason

If we sort this out, we might add some info on how to build this documentation locally to the Readme, to make further contribution easier.

---

¹ this is apparently due to the fact that Sphinx changed this in Changed in version 2.0: The default is changed to 'index' from 'contents'. So I assume you use version 1.something

[atoav]

Okay the sphinx installed by apt-get install python-sphinx shows the same problems.

Edit: weird – when I delete the line with :caption: Contents: on it, and use my own conf.py it works. Although the documentation for sphinx clearly states this is using :caption: is possible...

[carrotIndustries]

I just added my conf.py and Makefile. With sphinx installted, make html should be all you need to build the docs. I'm using

$ sphinx-build --version
sphinx-build 2.0.1