Kann Sphinx Links zu Dokumenten erstellen, die sich nicht in Verzeichnissen unterhalb des Stammdokuments befinden?

Ich verwende Sphinx, um ein Nicht-Python-Projekt zu dokumentieren. Ich möchte ./docOrdner in jedem Submodul verteilen , die submodule_name.rstDateien enthalten , um dieses Modul zu dokumentieren. Ich möchte diese Dateien dann in die Master-Hierarchie einfügen, um eine Spezifikation für das gesamte Design zu erstellen.

Dh:

Project
  docs
    spec
      project_spec.rst
      conf.py
  modules
    module1
      docs
        module1.rst
      src
    module2
      docs
        module2.rst
      src

Ich habe versucht, Dateien project_spec.rstwie folgt in den Hauptdokumentbaum aufzunehmen:

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

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

Diese Fehlermeldung führt jedoch zu:

WARNUNG: toctree enthält Verweise auf nicht vorhandene Dokumente u'modules / module1 / docs / module1 '

Ist es nicht möglich, ../irgendwie in einem Dokumentpfad zu verwenden ?

Update: Conf.py-Speicherort hinzugefügt

Update: Abgesehen von dem unten stehenden Include-Trick ist dies (2019) immer noch nicht möglich. Es gibt ein offenes Problem, das immer weiter vorangetrieben wird: https://github.com/sphinx-doc/sphinx/issues/701

Ja, du kannst!

Erstellen Sie anstelle eines Symlinks (der unter Windows nicht funktioniert) ein Stub-Dokument, das nur eine .. include::Direktive enthält.

Ich bin auf diesen Versuch gestoßen, eine Verknüpfung zu einer README-Datei herzustellen, die sich oben im Quellbaum befindet. Ich habe Folgendes in eine Datei mit dem Namen eingefügt readme_link.rst:

.. include:: ../README

Dann index.rstließ ich den Baum so aussehen:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

Und jetzt habe ich einen Link zu meinen Versionshinweisen auf meiner Indexseite.

Vielen Dank an http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html für den Vorschlag

Es scheint, dass die Antwort Nein lautet. Die im toc-Baum aufgelisteten Dokumente müssen sich im Quellverzeichnis befinden , dh im Verzeichnis , das Ihr Masterdokument und conf.py(und alle Unterverzeichnisse) enthält.

Aus der Sphinx-Dev-Mailingliste :

Bei STScI schreiben wir Dokumentation für einzelne Projekte in Sphinx und erstellen dann ein "Masterdokument", das (unter Verwendung von toctree) eine Reihe dieser anderen projektspezifischen Dokumente enthält. Zu diesem Zweck erstellen wir im doc-Quellverzeichnis des Masterdokuments Symlinks zu den doc-Quellverzeichnissen des Projekts, da toctree anscheinend keine Dateien außerhalb des doc-Quellbaums einschließen möchte.

Anstatt Dateien mit zu kopieren, können shutilSie versuchen, allen Modulen im Project/docs/specVerzeichnis Symlinks hinzuzufügen . Wenn Sie einen Symlink zu Ihnen erstellen, Project/modulesverweisen Sie auf diese Dateien in Ihrem toc-Baum einfach wie modules/module1/docs/module1usw.

Fügen Sie in conf.py die relativen Pfade mit sys.path und os.path zum System hinzu

Beispielsweise:

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'))

Verwenden Sie dann wie gewohnt Ihre index.rst und verweisen Sie auf die ersten Dateien im selben Verzeichnis. Also in meiner index.rst in meinem lokalen Sphinx-Ordner:

Contents:

.. toctree::
   :maxdepth: 4

   Package1 <package1.rst>
   Package2 <package2.rst>
   Package3 <package3.rst>

Dann sollten Sie in package1.rst in der Lage sein, normal auf die relativen Pakete zu verweisen.

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:

Es ist auch möglich, Sphinx so zu konfigurieren, dass nur die Datei index.rst im Stammverzeichnis und alle anderen Sphinx-Dateien in Project / docs enthalten sind:

Für Windows habe ich alle Sphinx-Dateien und Verzeichnisse (außer index.rst) in docs / verschoben und Folgendes geändert:

docs/make.bat: Veränderung

set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS%  .

zu

set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS%  -c . ..

docs/conf.py: Hinzufügen

sys.path.insert(0, os.path.abspath('..'))

Ich habe mein ziemlich ähnliches Problem mit dem Unterschied gelöst, dass ich ein externes Jupyter-Notebook einbauen wollte. Ich hatte nbsphinx installiert, konnte es aber nicht zum Laufen bringen. Was hat nicht funktioniert:

1. Ich hatte das Verzeichnis, in das ich das Stammverzeichnis aufnehmen wollte:

   conf.py:

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

2. Die Verwendung der .. include:: directiveDatei war in der Dokumentation enthalten, aber wie sie ist.

Schließlich löste das Problem die Installation des Pakets nbsphinx-link

Eine Lösung, wenn es wirklich unmöglich ist, relative Links zu verwenden, die gesichert werden, ../besteht darin, dass ich shutildie Dateien in den Spezifikationsordnerbaum in der Spezifikation kopieren könnte conf.py, aber ich würde lieber nicht mehrere Kopien haben, es sei denn, dies ist absolut notwendig.