Изменить главный файл 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 не входит ни в какое дерево c. Что можно исправить, используя 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.