Использование Sphinx для генерации документа Python с использованием: glob:

Question

Я новичок в сфинксе.

Файл /home/user/myproject/docs/source/index.rst выглядит следующим образом:

My project contents:

.. toctree::
   :glob:

   *

Я получаю следующее сообщение о запуске $ make html под /home/user/myproject/docs/:

checking consistency... /home/user/myproject/docs/source/design/index.rst:: WARNING: document isn't included in any toctree

Что я сделал неправильно? Я бы хотел, чтобы Sphinx автоматически генерировал структуру в зависимости от иерархии каталогов.

Answer 1

Я не думаю, что это поддерживаемая операция.

К счастью, это тоже не очень желательно, так как вы обычно хотите, чтобы части вашей документации отображались в определенном порядке.

Answer 2

Если вы хотите просто сбросить все свои исходные файлы в source без иерархии папок, это возможно. В качестве альтернативы вы можете написать подпрограмму и запустить ее из Makefile перед вызовом sphinx-build.

Как упоминал Майк, :glob: будет просто извлекать файлы в алфавитном порядке по имени файла. Смотри документы здесь .

Вы можете использовать «globbing» в директивах toctree, задав опцию флага glob. Затем все записи сопоставляются со списком доступных документов, и совпадения вставляются в список в алфавитном порядке.

Если вы хотите использовать :glob: и поддерживать порядок со всеми своими файлами в source, вам нужно поставить префикс .rst для файлов с номерами.

Пример * ** тысяча двадцать-один * тысяча двадцать два source ├── index.html ├── 1_intro.rst ├── 2_install.rst └── 3_more-than-you-want-to-know.rst Тем не менее, вам, конечно, нужно будет переименовать файлы, если вы решите, что хотите, чтобы они были упорядочены по-другому, а не перемещать порядок явного списка в index.rst.