更改 sphinx-build 主文件

Question

我可以告诉你 sphinx-build 别找 index.rst.

$ echo 'test' > readme.rst
$ sphinx-build -C . ./build readme.rst

这将抱怨索引文件丢失

master file /.../index.rst not found

然而，我们可以解决这个问题

$ ln -s readme.rst index.rst
$ sphinx-build -C . ./build readme.rst

这实际上将建立两个 index.rst 和 readme.rst 它将抱怨 readme.rst 不包含在任何toc树中。这可以通过使用 mv 而不是 ln. 然而，我不想为了满足奇怪的需求而到处移动文件。sphinx-build 要有一个索引文件。我也不希望到处都是滞留的链接。

我可以改变主文件的位置吗？类似于（这行不通）。

$ sphinx-build -C -D 'master_file=readme.rst' . ./build

或者我可以让它跳过所有的索引文件吗？类似于(这行不通)：或者我可以让它全部跳过索引文件？

$ sphinx-build -C -D 'exclude_patterns=index.rst' . ./build readme.rst

或者有其他方法解决这个问题吗？

Answer 1

首先重命名你的 index.rst 到 readme.rst.

然后您可以指定 master_doc 配置选项 无论是在你 conf.py 并建立你的文档，或者在你的文档中覆盖该值。conf.py 在命令行上建立文档时。

中指定的 conf.py

$ sphinx-build . ./build

仅在命令行中指定

$ sphinx-build . ./build -D master_doc='master'

Answer 2

怎么样。

sphinx-build -C . ./build readme.rst -D master_doc='readme'    

详细点

$ ls
readme.rst
$ sphinx-build -C . ./build readme.rst -D master_doc='readme'
Running Sphinx v1.8.5
making output directory...
building [mo]: targets for 0 po files that are specified
building [html]: 1 source files given on command line
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] readme                                                          
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] readme                                                           
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in build.
$ ls
build       readme.rst

我在使用Sphinx 3.0.2时也是这样的。