CI3 docs cannot be compiled with latest Sphinx

[orionstar]

The latest version of Sphinx can't compile the CI3 docs. The docs need an update or in the installation guide should be marked the specific sphinx version as a quickfix, because easy_install sphinx installs the latest: easy_install sphinx==1.2.3

[jim-parry]

Not sure what you are doing differently ... it works well for me, with sphinx 1.2.3, just as described in the README.rst.

[orionstar]

Yeah it works with 1.2.3, but if you follow the readme and you install sphinx with the easy_install sphinx command without specifiing the exact version, you will end up with version 1.3 and with that the build proccess fail. I've tried it on Windows 8.1 and Debian too.
So i think the readme should mention that we MUST use version 1.2.3 of sphinx to compile the docs.

As a quickfix i recommended the modification the existing install guide's step 2 to the following: easy_install sphinx==1.2.3

Later the docs needs an update to be compatible with 1.3.

[jim-parry]

Hmmm. According to the Sphinx site, 1.2.3 is the current version, and what should result from an easy_install. They show 1.3 as the "in development" version.

However, the "default" download for Sphinx seems to be delivering 1.3b2, the beta. That is curious, and not what I would consider "normal" practice!

You do have a valid point, and I will amend the directions for building the user guide, and then address the sphinx incompatibilities in it, in anticipation of the sphinx upgrade.