sphinx-build: error: argument -d/--maxdepth: invalid int value

[adamjstewart]

I recently updated to the latest version of Sphinx and am now unable to build the documentation for my project.

Problem

When I try to build the documentation for my project, I 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

Procedure to reproduce the problem

$ git clone https://github.com/spack/spack.git
$ cd spack/lib/spack/docs
$ make

Error logs / results

This was first reported in spack/spack#8491 (comment). This issue appears to be identical to readthedocs/readthedocs-build#44. The RtD issue suggests locking the version of Sphinx to 1.7.0. Indeed, this issue has never caused us trouble as we lock our version to 1.7.0 for Travis and RtD, but I would like to be able to build the docs locally.

Expected results

The docs should build correctly. According to sphinx-build --help, -d should accept a path, not an int:

  -d PATH           path for the cached environment and doctree files
                    (default: OUTPUTDIR/.doctrees)

Perhaps this is coming from sphinx-apidoc?

  -d MAXDEPTH, --maxdepth MAXDEPTH
                        maximum depth of submodules to show in the TOC
                        (default: 4)

Reproducible project / your project

https://github.com/spack/spack

Environment info

• OS: macOS 10.13.5
• Python version: 3.6.4
• Sphinx version: 1.7.5

[adamjstewart]

Additional details: In our conf.py, we actually run sphinx.apidoc.main, but not with the -d option. Could it be pulling in the command-line arguments erroneously?

[adamjstewart]

As I suspected, sphinx.apidoc.main appears to be the culprit. If I add print(argv) to the beginning of sphinx.ext.apidoc.main, it prints sys.argv, not the arguments I am passing to it. If I change the following line in my conf.py:

sphinx.apidoc.main([...])                                  

to:

sphinx.apidoc.main(argv=[...])                                  

or:

sphinx.ext.apidoc.main([...])

it solves the problem.

I'm actually wondering if my changes in #3668 are related to this bug. I hope I didn't break anything...

[adamjstewart]

@tk0miya I tracked down the problem to this particular commit:
b5bae23#diff-65ef293822255803d59c56efd9002e27

If I undo the args = args[1:] change to sphinx.apidoc.py, I can resolve this issue. Was #4623 related to #3668? I wonder if they are conflicting.

[tk0miya]

Sorry for inconvenience. This is a bug of sphinx.apidoc:main(). The interface was changed from past release. It's not intended.
Since 1.7, sphinx.apidoc has been moved to sphinx.ext.apidoc, and removed its first argument. At present, sphinx.apidoc:main() provides a helper function to keep compatibility. But it will be removed in Sphinx-2.0.

I just pushed the fix for sphinx.apidoc:main() in #5106. Could you check it please?

[adamjstewart]

Since 1.7, sphinx.apidoc has been moved to sphinx.ext.apidoc, and removed its first argument. At present, sphinx.apidoc:main() provides a helper function to keep compatibility. But it will be removed in Sphinx-2.0.

Any idea how far off Sphinx-2.0 is? We're trying to maintain compatibility with as many versions of Sphinx as we can, so we may have to check the Sphinx version before importing.

[tk0miya]

How about checking ImportError?

try:
    # Sphinx-1.7 or above
    from sphinx.ext import apidoc
    apidoc.main(argv[1:])
except ImportError:
    # Sphinx-1.6.x or older
    from sphinx import apidoc
    apidoc.main(argv)

Of course, you can use sphinx.version_info.

[tk0miya]

As discussed, the interface of sphinx.apidoc:main() has been broken. Now I just fixed it with #5106.

Note: The argument of sphinx.ext.apidoc:main() is different with sphinx.apidoc:main()'s. It's intentional.

Thank you for reporting.