Build process leaves out important detail - cwd

[jaraco]

In the RTD docs, the build process suggests that all RTD does in invoke build-sphinx in a checkout of the project, but there appears to be an implicit step where it changes directory to docs/ first.

This issue led to this pull request in setuptools.

I suggest RTD should document this implicit step or not require that step through a technique such as suggested in #889.

[ericholscher]

Agreed, the build process is definitely not documented well. However, Sphinx generally is run from the directory with the conf.py file in it -- which is what we do. So I think this is a pretty standard usage, but should be explicitly documented.

+1 on updating the docs.

[frontendphil]

I currently run into problems because of this behaviour. I tried to circumvent an i18n issue with images by having multiple conf.py files. One for each language. Those would then always include the regular conf.py and overwrite what's needed. This works great then doing a sphinx-build -c lang_dir/ . _build/html But this fails completely when you first go into lang_dir and execute the sphinx-build from there.

The main problem is of course, that there seems to be no really good way to have i18n for images. That's why my approach is having images in language directories and copy the correct images to a general directory before the build starts. If there is any better way to fix this, I'm open for suggestions.

[ericholscher]

This should be fixed in #1524 -- our build process output is now much more explicit.