Может ли сфинкс ссылаться на документы, которые не находятся в каталогах ниже корневого документа?

Я использую 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.rsttoctree главного документа следующим образом:

.. toctree::
   :numbered:
   :maxdepth: 2

   Module 1 <../../modules/module1/docs/module1>

Однако это сообщение об ошибке приводит к следующему:

ВНИМАНИЕ: toctree содержит ссылку на несуществующий документ u'modules / module1 / docs / module1 '

Разве это невозможно как-то использовать ../в пути к документу?

Обновление: добавлено расположение conf.py

Обновление: кроме трюка с включением ниже, это все еще (2019) невозможно. Существует нерешенная проблема, которая постоянно выдвигается вперед: https://github.com/sphinx-doc/sphinx/issues/701

Да, ты можешь!

Вместо символической ссылки (которая не работает в 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) ряд других документов для конкретных проектов. Для этого мы создаем символические ссылки в исходном каталоге документа главного документа на каталоги исходных документов проекта, поскольку 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:

Также можно настроить sphinx так, чтобы в корне был только файл index.rst, а все остальные вещи sphinx в Project / docs:

Для окон я переместил все файлы и каталоги sphinx (кроме 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('..'))

Я решил свою довольно похожую проблему с той разницей, что хотел включить внешний блокнот jupyter. Я установил nbsphinx, но не смог заставить его работать. Что не вышло:

1. У меня был каталог, в который я хотел включить корень в путь:

   conf.py:

   import os import sys sys.path.insert(...

2. Использование .. include:: directiveфайла было включено в документацию, но как есть.

Наконец, проблема была решена путем установки пакета nbsphinx-link.

Одно из решений, если действительно невозможно использовать относительные ссылки, которые создают резервную копию, ../- это то, что я мог бы использовать shutilдля копирования файлов в дерево папок спецификации в conf.pyспецификации, но я бы предпочел не иметь нескольких копий, если это абсолютно необходимо.