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

90

Я использую 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

python  python-sphinx  symlink  toctree 
— mc_electron
источник
Вам нужно добавить .rstрасширение к строке Module 1 <../../modules/module1/docs/module1>?
— Крис
Я так не думаю, потому что в Sphinx Docs : поскольку исходные файлы reST могут иметь разные расширения (кому-то нравится .txt, кому-то нравится .rst - расширение можно настроить с помощью source_suffix), а разные ОС имеют разные разделители путей, Sphinx абстрагирует их: все «имена документов» относятся к исходному каталогу, расширение удаляется, а разделители путей преобразуются в косую черту.
— mc_electron
Хорошо, только предположение! Я предполагаю, что source_suffixэто установлено .rstв вашем conf.pyфайле конфигурации. Кроме того, где этот файл в иерархии каталогов, поскольку кажется, что все пути относятся к этому файлу?
— Крис
Да, source_suffixустановлен .rstи conf.pyнаходится в той же папке, что иproject_spec.rst файл.
— mc_electron

Ответы:

108

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

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

— Дэн Менес
источник
5
Если в README есть изображения или аналогичные, относительные пути которых недействительны в каталоге, в котором находится index.rst, как вы с этим справитесь? Я получаю ошибку "файл изображения не читается".
— Lucas W
Да, вы также можете сделать это в Unix с помощью символических ссылок. Вы можете создать ссылку с тем же именем, что и у docs-folder (т.е. docs), которая ссылается на current-dir ('.'). Затем вы можете использовать: download: docs\foo.rstи это будет работать для файлов внутри docsпапки или ее родительской папки.
— ankostis
1
Я только что вернулся сюда и принял этот ответ, спасибо! Не уверен насчет изображений, но вы всегда можете скопировать их в conf.py.
— mc_electron
11
Мне нужно было использовать в .. include:: ../readme.rstтом числе расширение.
— nu everest
1
Чтобы включить только часть README.rst: muffinresearch.co.uk/…
— ederag
14

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

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

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

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

— Крис
источник
3
Это очень плохо. Одно из преимуществ, которые я вижу в попытке перейти с документов Word на Sphinx, заключается в том, что вы можете импортировать аппаратный модуль многократного использования в свой проект и просто включить его документацию в основную документацию для проекта. Я бы использовал символические ссылки, но, увы, я использую окна.
— mc_electron
Для потомков я попытался добавить папку doc подмодуля sys.pathв файл conf.py, но это не сработало.
— mc_electron
1
@mc_electron Для символьных ссылок в Windows используйте команду mklink.
— Джереми
11

В 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:
— Кингскот
источник
Это новое поведение? В какой версии это было добавлено?
— mc_electron 05
2
Было бы здорово, если бы подробности описали для новичков. Например, что есть Package1? Это впервые pathуказано с помощью sys.path.insert? Или где-нибудь есть учебник? Кажется, я не могу найти соответствующий документ.
— Manavalan Gajapathy
Package1- это именованная запись, поэтому в оглавлении в качестве заголовка раздела отображается «Package1».
— PabloC
3
Это позволяет вам автоматически загружать модули Python в другой каталог, но не позволяет вам включать файлы RST в другой каталог.
— mc_electron
1

Также можно настроить 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('..'))
— mrtnlrsn
источник
Благодарность! Эта конфигурация хорошо работает для меня, когда в одном репозитории есть несколько связанных пакетов, на которые есть ссылки из одной документации.
— Грегор Мюллеггер
1

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

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

    conf.py:

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

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

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

— Отчаянный инженер
источник
0

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

— mc_electron
источник
Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.