Skip to content
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
ghost opened this issue Feb 26, 2015 · 3 comments
Closed

fail to build the documentation in 12.2 #354

ghost opened this issue Feb 26, 2015 · 3 comments

Comments

@ghost
Copy link

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


@ghost
Copy link
Author

@ghost ghost 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?

@ghost
Copy link
Author

@ghost ghost commented Feb 26, 2015

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


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

@ghost
Copy link
Author

@ghost ghost 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

@ghost ghost added major bug labels Mar 29, 2016
@ghost ghost closed this Mar 29, 2016
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
0 participants