In "make html", don't use the -W flag with Sphinx. This makes it
possible to create the documentation with Sphinx 1.0 without errors,
as the warning about using old-style C markup isn't turned to an
error.
Don't build documentation in "make check". Instead, add a new make
target "check-doc" to build the documentation with the -W flag.
The problem is that Sphinx can only read input files from a single
directory. In VPATH builds, the source and build trees are separate,
and the changes.rst went into the build tree.
This patch solves the issue by using cfunc as the Sphinx default role.
CHANGES is preprocessed to convert json_*() function names to Sphinx
:cfunc: cross references. This is to keep CHANGES more readable in
both plain text and HTML.
To keep the distchecks for the documentation, the documentation has to
be built in the check target instead of distcheck-hook.
While at it, rename doc/.build to doc/_build. This naming is the
default with sphinx 0.6.2.
