how to tell sphinx that source code is in this path and build in that path

Question

I want to run sphinx on a library in a conda virtual environment with path

/anaconda/envs/test_env/lib/site-packages/mypackage

and put the html files in the path

/myhtmlfiles/myproject

where my conf.py and *.rst files are in the path

/sphinx/myproject

---

question
What are the conf.py settings I need to edit to make this happen when I run

make html

Answer 1

To change the output directory you have Makefile so you do not have to do this through conf.py

Looks like you have html target in the Makefile:

If it looks something like this:

html:
    $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

Then you can just change the variables:

SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
BUILDDIR      = ../../build/main

ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) ./

While this takes the source from current directory, to use different directory:

ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) ./mySourceFolder

If you run sphinx-build on command line you can do these things without make, see the sphinx-build -h:

% sphinx-build -h
usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]

Generate documentation from source files. sphinx-build generates documentation
from the files in SOURCEDIR and places it in OUTPUTDIR. It looks for 'conf.py'
in SOURCEDIR for the configuration settings. The 'sphinx-quickstart' tool may
be used to generate template files, including 'conf.py' sphinx-build can
create documentation in different formats. A format is selected by specifying
the builder name on the command line; it defaults to HTML. Builders can also
perform other tasks related to documentation processing. By default,
everything that is outdated is built. Output only for selected files can be
built by specifying individual filenames.

positional arguments:
  sourcedir         path to documentation source files
  outputdir         path to output directory
  filenames         a list of specific files to rebuild. Ignored if -a is
                    specified

optional arguments:
  -h, --help        show this help message and exit
  --version         show program's version number and exit

general options:
  -b BUILDER        builder to use (default: html)
  -a                write all files (default: only write new and changed
                    files)
  -E                don't use a saved environment, always read all files
  -d PATH           path for the cached environment and doctree files
                    (default: OUTPUTDIR/.doctrees)
  -j N              build in parallel with N processes where possible (special
                    value "auto" will set N to cpu-count)

build configuration options:
  -c PATH           path where configuration file (conf.py) is located
                    (default: same as SOURCEDIR)
  -C                use no config file at all, only -D options
  -D setting=value  override a setting in configuration file
  -A name=value     pass a value into HTML templates
  -t TAG            define tag: include "only" blocks with TAG
  -n                nit-picky mode, warn about all missing references

console output options:
  -v                increase verbosity (can be repeated)
  -q                no output on stdout, just warnings on stderr
  -Q                no output at all, not even warnings
  --color           do emit colored output (default: auto-detect)
  -N, --no-color    do not emit colored output (default: auto-detect)
  -w FILE           write warnings (and errors) to given file
  -W                turn warnings into errors
  --keep-going      with -W, keep going when getting warnings
  -T                show full traceback on exception
  -P                run Pdb on exception

For more information, visit <http://sphinx-doc.org/>.

usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]

The first argument is your source and the second is your output directory. You can't change source directory from conf.py as that is in your source directory, it's like knowing your source directory before deciding what the source directory is. When you point sphinx to a conf.py then it's already decided what the source directory is.

Answer 2

Place a python file with this content into the source folder of sphinx

import os
from subprocess import call

# path to source
this_path = os.path.dirname(os.path.abspath(__file__))
packagedir = os.path.join(this_path, '..','some folder', 'some other folder')  # this is the path to your source!
outputdir = os.path.join(this_path)

# Command you should run
# sphinx-apidoc [options] -o outputdir packagedir [pathnames]

call(["sphinx-apidoc", "-o", outputdir, packagedir])
call([os.path.join('..', 'make.bat'), 'html'])
call([os.path.join('..', 'make.bat'), 'latex'])

Enjoy

Answer 3

You can edit the Makefile, as others mentioned. I normally just use the sphinx-build command.

$ sphinx-build [options] sourcedir outputdir (html is the default build option; you can specify it using -b html)

The location of the package only matters if you're auto-generating api docs. If you're running the command to build from /sphinx/myproject, you'd use:

$ sphinx-build ./ /myhtmlfiles/myproject

This places the build output in a sub-directory, /sphinx/myproject/myhtmlfiles/myproject. If the build location isn't a subdirectory of sphinx/myproject, be sure to specify the correct path.

If you want to auto-generate api docs, you'll want to use sphinx-apidoc:

$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]

Answer 4

The output directory is not a conf.py setting. It is an argument (builddir) to sphinx-build. Set it in the Makefile.

You tell Sphinx where the package is by updating sys.path in conf.py.

Answer 5

make is not a sphinx command. That command actually runs either a make with a Makefile or make.bat (depending on your operating system), which then locates the relevant files before invoking sphinx-build. You will need to modify the make files and/or set the proper environmental variables.