Skip to content

Allow docs to be built with Sphinx 1.7.1+#8500

Merged
becker33 merged 2 commits intospack:developfrom
adamjstewart:docs/sphinx-apidoc
Jun 19, 2018
Merged

Allow docs to be built with Sphinx 1.7.1+#8500
becker33 merged 2 commits intospack:developfrom
adamjstewart:docs/sphinx-apidoc

Conversation

@adamjstewart
Copy link
Copy Markdown
Member

@adamjstewart adamjstewart commented Jun 18, 2018

Fixes an issue reported by @twang15 in #8491.

Before

If you try to build Spack's documentation with Sphinx 1.7.1+, you encounter the following error message:

$ make
sphinx-build -b html -d _build/doctrees  -E . _build/html
Running Sphinx v1.7.5
usage: sphinx-build [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, ...]
sphinx-build: error: argument -d/--maxdepth: invalid int value: '_build/doctrees'

Configuration error:
The configuration file (or one of the modules it imports) called sys.exit()
make: *** [html] Error 2

This bug was introduced in sphinx-doc/sphinx#4624, which first appears in Sphinx 1.7.1. See sphinx-doc/sphinx#5104 for the nitty-gritty details.

The reason no one has noticed it until now is that we lock down our version of Sphinx to 1.7.0 for the documentation tests.

An alternative fix would be to replace sphinx.apidoc.main with sphinx.ext.apidoc.main. This solution was not chosen because sphinx.ext.apidoc did not exist before 1.7.0. This solution should work for all versions of Sphinx, although testing with older versions would be greatly appreciated.

@adamjstewart adamjstewart added the documentation Improvements or additions to documentation label Jun 18, 2018
@adamjstewart
Copy link
Copy Markdown
Member Author

adamjstewart commented Jun 18, 2018

According to sphinx-doc/sphinx#5104 (comment), sphinx.apidoc will be removed in Sphinx-2.0 and we will need to move to sphinx.ext.apidoc eventually. Not sure how wide of a version range we want to support. We could check the version of Sphinx when importing.

@adamjstewart
Copy link
Copy Markdown
Member Author

adamjstewart commented Jun 18, 2018

Okay, the latest commit future-proofs things so that the docs will build with Sphinx 2.0, whenever it is released. This has the beneficial side-effect of side-stepping the bug in sphinx.apidoc.main.

@becker33 becker33 merged commit 55d0d18 into spack:develop Jun 19, 2018
@adamjstewart adamjstewart deleted the docs/sphinx-apidoc branch June 19, 2018 02:50
@adamjstewart
Copy link
Copy Markdown
Member Author

adamjstewart commented Jun 19, 2018

According to one of the leading contributors to Sphinx, sphinx.ext.apidoc.main is not a public API and really shouldn't be used for this purpose.

Other developers have suggested using sphinx-contrib/apidoc to handle automatic documentation generation. See sphinx-doc/sphinx#5106 for more discussion.

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

Reviewers

1 more reviewer

@healther healther healther approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@adamjstewart @healther @becker33