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

87

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

mc_electron
quelle
Müssen Sie die .rstErweiterung zur Zeile hinzufügen Module 1 <../../modules/module1/docs/module1>?
Chris
Ich glaube nicht, weil in den Sphinx- Dokumenten: Da die reST-Quelldateien unterschiedliche Erweiterungen haben können (einige Leute mögen .txt, andere wie .rst - die Erweiterung kann mit source_suffix konfiguriert werden) und verschiedene Betriebssysteme unterschiedliche Pfadtrennzeichen haben, hat Sphinx abstrahiert sie: Alle „Dokumentnamen“ beziehen sich auf das Quellverzeichnis, die Erweiterung wird entfernt und Pfadtrennzeichen werden in Schrägstriche konvertiert.
mc_electron
OK, nur eine Vermutung! Also ich , dass anmaßen source_suffixwird auf .rstin Ihrer conf.pyKonfigurationsdatei. Wo befindet sich diese Datei in Ihrer Verzeichnishierarchie, da anscheinend alle Pfade relativ zu dieser Datei sind?
Chris
Ja, source_suffixist auf eingestellt .rstund conf.pybefindet sich im selben Ordner wie die project_spec.rstDatei.
mc_electron

Antworten:

105

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

Dan Menes
quelle
4
Wenn die README-Datei Bilder oder ähnliches enthält, die relative Pfade haben, die im Verzeichnis index.rst nicht gültig sind. Wie gehen Sie damit um? Ich erhalte die Fehlermeldung "Bilddatei nicht lesbar".
Lucas W
Ja, das können Sie auch unter Unix mit Symlinks tun. Sie können einen Link mit demselben Namen wie der Dokumentordner (dh docs) erstellen , der auf das aktuelle Verzeichnis ('.') Verlinkt. Dann können Sie docs\foo.rstFolgendes verwenden: download: und dies würde für Dateien innerhalb des docsOrdners oder seines übergeordneten Ordners funktionieren .
Ankostis
1
Ich bin gerade hier gelandet und habe diese Antwort akzeptiert, danke! Sie sind sich der Bilder nicht sicher, können sie jedoch jederzeit in die Datei conf.py kopieren.
mc_electron
10
Ich musste .. include:: ../readme.rsteinschließlich der Erweiterung verwenden.
Nu Everest
1
Um nur einen Teil der README.rst aufzunehmen: muffinresearch.co.uk/…
ederag
14

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.

Chris
quelle
3
Das ist sehr schade. Einer der Vorteile, die ich beim Wechsel von Word-Dokumenten zu Sphinx sehe, besteht darin, dass Sie ein wiederverwendbares Hardwaremodul in Ihr Projekt importieren und dessen Dokumentation einfach in die Hauptdokumentation für das Design aufnehmen können. Ich würde Symlinks verwenden, aber leider bin ich auf Windows.
mc_electron
Für die Nachwelt habe ich versucht, den Ordner submodule doc sys.pathin der Datei conf.py hinzuzufügen, aber das hat nicht funktioniert.
mc_electron
1
@mc_electron Verwenden Sie für Symlinks unter Windows den Befehl mklink.
Jeremy
11

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:
Ein Kingscote
quelle
Ist das neues Verhalten? In welcher Version wurde es hinzugefügt?
mc_electron
2
Wäre toll, wenn weiter beschrieben, um Anfänger zu informieren. Was ist zum Beispiel Package1? Wird das zuerst mit pathangegeben sys.path.insert? Oder gibt es irgendwo ein Tutorial? Ich kann das relevante Dokument anscheinend nicht finden.
Manavalan Gajapathy
Package1ist ein benannter Eintrag, sodass im Inhaltsverzeichnis "Paket1" als Titel des Abschnitts angezeigt wird.
PabloC
2
Auf diese Weise können Sie Python-Module automatisch in einem anderen Verzeichnis zuordnen, RST-Dateien jedoch nicht in ein anderes Verzeichnis aufnehmen.
mc_electron
1

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('..'))
mrtnlrsn
quelle
Vielen Dank! Diese Konfiguration funktioniert gut für mich, wenn sich mehrere verwandte Pakete in einem Repository befinden, auf die aus derselben Dokumentation verwiesen wird.
Gregor Müllegger
1

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

DesperateEngineer
quelle
0

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.

mc_electron
quelle