Может ли sphinx ссылаться на документы, которые не находятся в каталогах под корневым документом?
Я использую Sphinx для документирования не-Python проекта. Я хочу раздать ./doc папки в каждом подмодуле, содержащие submodule_name.rst файлы для документирования этого модуля. Затем я хочу добавить эти файлы в основную иерархию, чтобы создать спецификацию для всего проекта.
То есть:
Project
docs
spec
project_spec.rst
conf.py
modules
module1
docs
module1.rst
src
module2
docs
module2.rst
src
Я попытался включить файлы в мастер project_spec.rst документ toctree вот так:
.. toctree::
:numbered:
:maxdepth: 2
Module 1 <../../modules/module1/docs/module1>
Однако это сообщение об ошибке приводит к:
ВНИМАНИЕ: toctree содержит ссылку на несуществующий документ u'modules/module1/docs/module1'
Разве нельзя использовать ../ в пути документа как-нибудь?
Обновление: добавлено расположение conf.py
8 ответов
Да, ты можешь!
Вместо символической ссылки (которая не будет работать в Windows) создайте заглушку, в которой нет ничего, кроме .. include:: директивы.
Я столкнулся с этим, пытаясь связать файл README, который был в верхней части дерева исходных текстов. Я положил следующее в файл с именем readme_link.rst:
.. include:: ../README
Затем в index.rstЯ сделал так, что дерево выглядит так:
Contents:
.. toctree::
:maxdepth: 2
readme_link
other_stuff
И теперь у меня есть ссылка на мои заметки о выпуске на моей странице индекса.
Спасибо http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html за предложение
Кажется, что ответ "нет", документы, перечисленные в дереве toc-дерева, должны находиться в исходном каталоге, то есть в каталоге, содержащем ваш главный документ и conf.py (и любые подкаталоги).
Из списка рассылки sphinx-dev:
В STScI мы пишем документацию для отдельных проектов в Sphinx, а затем также создаем "главный документ", который включает (используя toctree) ряд этих других специфических для проекта документов. Для этого мы создаем символические ссылки в исходном каталоге doc мастер-документа на исходные каталоги doc проектов, поскольку toctree, похоже, не хочет включать файлы за пределы исходного дерева документа.
Так что вместо копирования файлов с помощью shutil Вы можете попробовать добавить символические ссылки на все ваши модули в Project/docs/spec каталог. Если вы создаете символическую ссылку на Project/modules Затем вы будете ссылаться на эти файлы в вашем дереве Toc-деревьев просто как modules/module1/docs/module1 и т.п.
В conf.py добавьте относительные пути к системе, используя sys.path и os.path
Например:
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../../Directory1'))
sys.path.insert(0, os.path.abspath('../../Directory2'))
Затем используйте ваш index.rst как обычно, ссылаясь на первые файлы в том же каталоге. Так в моем index.rst в моей локальной папке Sphinx:
Contents:
.. toctree::
:maxdepth: 4
Package1 <package1.rst>
Package2 <package2.rst>
Package3 <package3.rst>
Затем в package1.rst вы сможете просто ссылаться на соответствующие пакеты.
Package1 package
=====================
Submodules
----------
Submodule1 module
----------------------------------
.. automodule:: file_within_directory_1
:members:
:undoc-members:
:show-inheritance:
Submodule1 module
----------------------------------
.. automodule:: file_within_directory_2
:members:
:undoc-members:
:show-inheritance:
Я решил свою довольно похожую проблему с той разницей, что я хотел включить внешний ноутбук jupyter. Я установил nbsphinx, но не смог заставить его работать.Что не вышло:
У меня был каталог, в который я хотел включить корень:
conf.py:
import os import sys sys.path.insert(...Используя
.. include:: directiveфайл был включен в документацию, но как есть.
Наконец, что решило проблему, так это установка пакета nbsphinx-link
Мой ответ - это, по сути, @Dan Menes, но для парсера Myst вместо reStructured.
Я бы предпочел добавить это в качестве комментария к ответу @Dan Menes, поскольку он принадлежит ему, но комментарии не позволяют мне выполнять форматирование, синтаксис Myst чувствителен к новым строкам, а комментарии ограничены символами. Поэтому я отправляю его как отдельный ответ, даже если он связан с существующим ответом.
Чтобы включить Myst, вам нужно отформатировать его немного иначе:
```{include} ../main/post_installation_windows.md
```
Он также может обернуть себя, чтобы выполнить реструктурированную разметку (который затем включенный файл будет обрабатываться так, как он написан в реструктурированной):
```{eval-rst}
.. include:: snippets/include-rst.rst
```
Однако использовать собственный синтаксис Myst проще. И у него есть лучшие функции, например, простое включение файла не приведет к правильному разрешению любых ссылок внутри включенного файла, в то время как include-literal должен:
```{include-literal} ../../example.md
:language: md
```
Как вы могли обнаружить, включение простого документа - это нормально, но включение сложного документа со многими ссылками вызовет больше головной боли, поэтому я бы рекомендовал экспериментальный
Ссылка:https://myst-parser.readthedocs.io/en/latest/using/howto.html
Альтернативный метод, который не требует создания файлов-заглушек, заключается в использовании абсолютных ссылок (начиная с
/) в корне вашего toctree и установив в качестве исходного каталога наименьшего общего предка при вызове. Пример макета каталога:
/path/to/common/ancestor
├── a
│ └── foo.rst
├── b
│ ├── bar.rst
│ ├── x
│ │ └── index.rst
│ └── y
│ └── boz.rst
└── c
└── baz.rst
А также
b/x/index.rst:
.. toctree::
/a/foo
/b/bar
/b/y/boz
/c/baz
И ваш
sphinx-build команда может выглядеть так:
sphinx-build -c <confdir> -b html -D masterdoc=b/x/index /path/to/common/ancestor <outdir>
Я тестировал это со сфинксом
3.0.2.
Также можно настроить sphinx так, чтобы в корне был только файл index.rst и все остальные вещи sphinx в Project/docs:
Для окон я переместил все файлы sphinx и dirs (кроме index.rst) в docs/ и изменил:
docs/make.bat: Изменить
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
в
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% -c . ..
docs/conf.py: Добавлять
sys.path.insert(0, os.path.abspath('..'))
Одно из решений, если действительно невозможно использовать относительные ссылки, которые поддерживают ../ это то, что я мог бы использовать shutil скопировать файлы в дерево папок спецификации в conf.py для спецификации, но я бы предпочел не иметь несколько копий, если это абсолютно необходимо.