fail to build the documentation in 12.2

[ghost]

Originally reported by: Anonymous

---

PYTHONPATH=/home/packages/setuptools/python-setuptools-12.2
sh -c 'cd docs && sphinx-build -b html -d build/doctrees . build/html'
Making output directory...
Running Sphinx v1.2.3

Exception occurred:
File "/home/packages/setuptools/python-setuptools-12.2/linkify.py", line 37, in _linkify
with open(source) as source:
IOError: [Errno 2] No such file or directory: 'CHANGES.txt'
The full traceback has been saved in /tmp/sphinx-err-UxnBLM.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at https://bitbucket.org/birkenfeld/sphinx/issues/. Thanks!

not sure if this really is a sphinx issue ...

---

• Bitbucket: https://bitbucket.org/pypa/setuptools/issue/354

[ghost]

Original comment by jaraco (Bitbucket: jaraco, GitHub: jaraco):

---

It's not a sphinx issue. It's an issue with the script that adds links to the changelog. It assumes that the docs are built from the root of the repository and not from 'docs/'.

The fix is not obvious to me. It seems the sphinx-built command (and other systems like read the docs) are pretty opinionated about the command being run from the 'docs' directory. However, the 'setup.py build_sphinx' script is typically invoked from the root of the repository. I'm not sure how to readily and elegantly accommodate both modes.

To make matters worse, the latest, unreleased code no longer uses the linkify script, but instead relies on a third-party library. This means that doc builds will require prerequisite libraries to be installed before building the docs.

Therefore, I recommend instead using the setuptools command to build docs. Simply:

python setup.py build_sphinx

That will download any requisite libraries and build the docs in the build/sphinx directory. Will that work for your purposes?

[ghost]

Original comment by jaraco (Bitbucket: jaraco, GitHub: jaraco):

---

Formally describe the supported documentation build process. Fixes #354.

[ghost]

Original comment by jaraco (Bitbucket: jaraco, GitHub: jaraco):

---

Published with the 12.3 release: https://pythonhosted.org/setuptools/developer-guide.html#building-documentation