Sphinx - specify source directory (sphinx-build arguments)

[sid-kap]

Hi,

It looks like the default sphinx builder assumes that the source directory is the same as the configuration directory.
In https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/sphinx.py#L128,
it looks like it CDs to the configuration directory and runs sphinx-build specifying "." as the source directory.

I want a directory structure as follows:

project/
  - docs/
    - conf.py
    - src/
    - _build/

where project/docs is my configuration directory and project/docs/src is my source directory.

It looks like the only way to do this is to write my own builder.
Is there an easier way to do this? If not, would you consider adding an easier way to do this?

[gregmuellegger]

Hi, I think we won't add this very soon as there are alreadya lot configuration options in the project's admin panel. However we are working on a configuration that can be put in your directory (i.e. a readthedocs.yml config in your repo). We have enough room there for as many config options as we want and will consider it there. Stay tuned :)

[rweickelt]

The yml config file has been around for a while. Is this now doable?

[humitos]

Hi @rweickelt! The documentation for the yaml file is at http://docs.readthedocs.io/en/latest/yaml-config.html and it seems that this is not supported yet :(

[agjohnson]

You can always create a placeholder project/docs/src/conf.py that does something like import * from ..conf -- or prepend the parent path to sys.path. Either way, solving this is probably unlikely in RTD, and is more of a Sphinx issue anyways. Closing this for now

[pradyunsg]

I request reconsidering the addition of this in the YAML file. I'm currently working on reorganizing pip's documentation, to simplify the build process. This reorganization is intended to split up pip's man pages and html pages.

I want to be able to specify the source directory (either docs/html or docs/man) while pointing to the same conf.py (docs/conf.py) file.

Either way, solving this is probably unlikely in RTD, and is more of a Sphinx issue anyways

I disagree.

Sphinx allows specifying different directories for conf.py vs the source directory. It does default to conf.py being at <source>/conf.py. RTD doesn't expose the ability to customize this. I think the fix is to enable RTD to fix this.

---

On a slightly different note... Thanks for all the work on RTD. :)

[agjohnson]

I think the workaround above still stands. You can have a single conf.py with the per-directory conf.py that doesn't need to be edited. We are trying to keep bloat out of our yaml config, this particular case isn't common enough for us to warrant the work to add this feature.

Is there a reason using conf.py as a package doesn't work for your case? For example, some untested pseudo sphinx config:

docs/conf.py:

project = "..."
version = ".."
# Rest of your common sphinx config

docs/html/conf.py:

import os
import sys

sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))

from conf import *

# Override what you need
project = "..."

[pradyunsg]

Of course, it works. I'm actually going to not do a duplicated import and moved the file to the HTML directory, letting RTD build the HTML docs since the man pages are anyways going to not be built on RTD.

I'll withdraw my proposal - the workaround is simple enough in nearly all cases and there is no need to ask for low-benefit work from others. :)