Readthedocs.org: -d/--maxdepth: invalid int value: '_build/doctrees-readthedocs'

[jakirkham]

Details

• Project URL: https://readthedocs.org/projects/dask-image/
• Build URL (if applicable):https://readthedocs.org/projects/dask-image/builds/6874253/
• Read the Docs username (if applicable): (same as GitHub)

Expected Result

The docs would build.

Actual Result

Snippet taken from the linked log above.

$ python /home/docs/checkouts/readthedocs.org/user_builds/dask-image/conda/latest/bin/sphinx-build -T -b readthedocs -d _build/doctrees-readthedocs -D language=en . _build/html

Running Sphinx v1.7.1
loading translations [en]... done
making output directory...
loading pickled environment... not yet created
usage: usage: sphinx-build [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, ...]
sphinx-build: error: argument -d/--maxdepth: invalid int value: '_build/doctrees-readthedocs'

[humitos]

Giving a little more of context, the command is called at https://github.com/rtfd/readthedocs.org/blob/8f2d59cdcdee0050feece79465d1a6c5c903ecf5/readthedocs/doc_builder/backends/sphinx.py#L195-L204

It's weird that it says -d/--maxdepth as it one is the short form and the other the long form, but the sphinx-build documentation says that -d is a path, not an int: http://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-d

So, maybe something is wrong in Sphinx itself? :/

[jakirkham]

Maybe it's coming from sphinx-apidoc?

https://github.com/sphinx-doc/sphinx/blob/2994c125132b6beb73c51de4cc224a2b1d55f741/sphinx/ext/apidoc.py#L325-L328

[humitos]

@jakirkham probably... do you know why this is happening? how do we use one -d (from Sphinx) or the other (from apidoc)?

[arh89]

I am seeing the same issue with a project that I work on - it seems to be either a bug or change in behaviour with the update from sphinx 1.7.0 to 1.7.1. Is there a straightforward way to force RTD to use v1.7.0?

[humitos]

@arh89 yes, you can create a docs/requirements.txt (or similar) and pin the packages as you need and use the YAML config: http://docs.readthedocs.io/en/latest/yaml-config.html#requirements-file

[cdwilson]

Pinning sphinx==1.7.0 in requirements.txt fixed this for me also. I'm getting the same error with 1.7.1.

[humitos]

Thanks @cdwilson!

I'm closing this issue since it's not a RTD bug or similar but a problem between sphinx and apidoc, and we already have the workaround proposed by @cdwilson.

Feel free to reopen if you consider. Thanks!

[jakirkham]

Unfortunately that doesn't work for us, @humitos. 😞

We are currently pinning Sphinx, but it appears that RTD overrides us later, which is causing the problem. Having our Sphinx version constraint respected by RTD would solve this issue for us on the RTD side.

Also can't reopen the issue as GitHub disallows users without write permissions to reopen issues closed by others.

[humitos]

@jakirkham thanks for your report.

This is a different problem I'd say since here, even that you are pinning the sphinx version via conda YAML file, RTD is running this command _after_ yours:

 conda install --yes --name latest mock pillow sphinx sphinx_rtd_theme

and then conda upgrades the sphinx package to the latest version. Can you open a new issue with an explanation to track this separately?

[jakirkham]

Thanks @humitos. Agree that it is a different problem. Have raised as issue ( https://github.com/rtfd/readthedocs.org/issues/3829 ). Please let me know if there is anything else we should add to that.

[jakirkham]

Do you have any ideas what might be happening here, @tk0miya?

[adamjstewart]

For anyone else who encounters this issue, I opened up an issue with Sphinx directly. In my case, the problem is caused by calling sphinx.apidoc.main inside of my conf.py. sphinx.apidoc.main is erroneously pulling in command-line args from sphinx-build, causing the error message you see. See https://github.com/sphinx-doc/sphinx/issues/5104 for more details.

[jakirkham]

Thanks for opening the upstream issue, @adamjstewart 😄

[jakirkham]

Added a workaround that solved the issue for me in this comment.