Может ли 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::
   :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

ОТВЕТЫ

Ответ 1

Да, вы можете!

Вместо символической ссылки (которая не будет работать в 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 за предложение

Ответ 2

Кажется, что ответ отрицательный, документы, перечисленные в toc-tree, должны находиться в исходном каталоге, то есть в каталоге содержащий главный документ и conf.py (и любые подкаталоги).

Из списка рассылки sphinx-dev:

В STScI мы пишем документацию для отдельных проектов в Sphinx, а затем также создаем "главный документ", который включает (используя toctree) ряд других документов, относящихся к конкретным проектам. Для этого мы создаем символические ссылки в исходном каталоге исходного документа doc в исходные каталоги проектов, так как toctree действительно не хочет включать файлы за пределами дерева исходных текстов.

Поэтому вместо копирования файлов с помощью shutil вы можете попробовать добавить символические ссылки ко всем вашим модулям в каталог Project/docs/spec. Если вы создадите символическую ссылку на Project/modules, вы будете ссылаться на эти файлы в своем дереве toc просто как modules/module1/docs/module1 и т.д.

Ответ 3

В 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>

Затем в пакете1.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:

Ответ 4

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

Ответ 5

Также можно настроить sphinx на наличие только файла index.rst в корневом каталоге и всех других сфинксов в 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('..'))