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

Question

Я новичок в Sphinx.

Файл /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: будет просто вытаскивать файлы в алфавитном порядке по имени файла. See the docs here.

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

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

Пример

source 
├── index.html 
├── 1_intro.rst 
├── 2_install.rst 
└── 3_more-than-you-want-to-know.rst 

Хотя, вы, конечно, необходимо переименовать файлы, если вы решите, что вы хотите, чтобы они заказали по-другому, а не перемещая порядок явного списка в index.rst.