New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fail to build the documentation in 12.2 #354

Closed
bb-migration opened this Issue Feb 26, 2015 · 3 comments

Comments

Projects
None yet
1 participant
@bb-migration

bb-migration commented Feb 26, 2015

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 ...


@bb-migration

This comment has been minimized.

bb-migration commented Feb 26, 2015

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?

@bb-migration

This comment has been minimized.

bb-migration commented Feb 26, 2015

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


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

@bb-migration

This comment has been minimized.

bb-migration commented Feb 26, 2015

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


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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment