Question

我想在具有路径

的conda虚拟环境中的库上运行sphinx

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

并将html文件放在路径

中

/myhtmlfiles/myproject

我的conf.py和*.rst文件位于路径

中

/sphinx/myproject

问题
当我运行

时，我需要编辑哪些conf.py设置才能实现此目的

make html

Answer 1

make不是sphinx命令。该命令实际上运行带有Makefile的make或make.bat（取决于您的操作系统），然后在调用sphinx-build之前找到相关文件。您需要修改make文件和/或设置适当的环境变量。

Answer 2

输出目录不是conf.py设置。它是sphinx-build的参数（builddir）。在Makefile中设置它。

您可以在conf.py中通过updating sys.path告诉Sphinx包裹的位置。

Answer 3

您可以像其他人提到的那样编辑Makefile。我通常只使用sphinx-build命令。

$ sphinx-build [options] sourcedir outputdir （html是默认的构建选项;您可以使用-b html）

指定它

只有在您自动生成api文档时，程序包的位置才有意义。如果您正在运行从/ sphinx / myproject构建的命令，那么您将使用：

$ sphinx-build ./ /myhtmlfiles/myproject

这会将构建输出放在子目录/sphinx/myproject/myhtmlfiles/myproject中。如果构建位置不是sphinx/myproject的子目录，请务必指定正确的路径。

如果您想自动生成api文档，则需要使用sphinx-apidoc：

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

Answer 4

将包含此内容的python文件放入sphinx的source文件夹

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'])

享受

Answer 5

要更改输出目录，您有 Makefile，因此您不必通过 conf.py 来执行此操作

看起来您在 html 中有 Makefile 目标：

如果它看起来像这样：

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

然后你可以改变变量：

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

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

虽然这从当前目录中获取源代码，但要使用不同的目录：

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

如果您在命令行上运行 sphinx-build，则无需 make 即可执行这些操作，请参阅 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/>.

用法：sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [文件名...]

第一个参数是您的源，第二个参数是您的输出目录。您不能更改 conf.py 中的源目录，因为它位于您的源目录中，这就像在决定源目录是什么之前了解您的源目录一样。当您将 sphinx 指向 conf.py 时，它已经决定了源目录是什么。

如何告诉sphinx源代码在此路径中并构建在该路径中

5 个答案: