Sphinx può collegarsi a documenti che non si trovano nelle directory sotto il documento radice?

Sto usando Sphinx per documentare un progetto non Python. Voglio distribuire ./doccartelle in ogni sottomodulo, contenenti submodule_name.rstfile per documentare quel modulo. Quindi voglio risucchiare quei file nella gerarchia principale per creare una specifica per l'intero progetto.

Cioè:

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

Ho tentato di includere file nel project_spec.rstdocumento master in una struttura in questo modo:

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

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

Tuttavia, questo messaggio di errore risulta:

ATTENZIONE: toctree contiene riferimenti a documenti inesistenti u'modules / module1 / docs / module1 '

Non è possibile utilizzare ../in qualche modo nel percorso di un documento?

Aggiornamento: aggiunta posizione conf.py

Aggiornamento: a parte il trucco di inclusione di seguito, questo (2019) non è ancora possibile. C'è un problema aperto che continua a essere portato avanti: https://github.com/sphinx-doc/sphinx/issues/701

Si, puoi!

Al posto di un collegamento simbolico (che non funzionerà su Windows), crea un documento stub che non contenga altro che una .. include::direttiva.

Mi sono imbattuto in questo cercando di collegarmi a un file README che era nella parte superiore dell'albero dei sorgenti. Ho inserito quanto segue in un file chiamato readme_link.rst:

.. include:: ../README

Quindi in index.rst, ho fatto apparire l'albero come:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

E ora ho un collegamento alle mie note di rilascio nella mia pagina indice.

Grazie a http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html per il suggerimento

Sembra che la risposta sia no, i documenti elencati nell'albero toc devono risiedere all'interno della directory di origine , cioè la directory contenente il tuo documento master econf.py (e le eventuali sottodirectory).

Dalla mailing list di sphinx-dev :

In STScI, scriviamo documentazione per singoli progetti in Sphinx, quindi produciamo anche un "documento master" che include (utilizzando toctree) una serie di questi altri documenti specifici del progetto. Per fare questo, creiamo collegamenti simbolici nella directory sorgente doc del documento master alle directory sorgente doc dei progetti, poiché toctree non sembra voler includere file al di fuori dell'albero sorgente doc.

Quindi, invece di copiare i file usando, shutilpotresti provare ad aggiungere collegamenti simbolici a tutti i tuoi moduli nella Project/docs/specdirectory. Se crei un collegamento simbolico a Project/moduleste, faresti riferimento a questi file nel tuo albero toc semplicemente come modules/module1/docs/module1ecc.

In conf.py, aggiungi i percorsi relativi al sistema usando sys.path e os.path

Per esempio:

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

Quindi usa il tuo index.rst come al solito, facendo riferimento ai primi file nella stessa directory. Quindi nel mio index.rst nella mia cartella Sphinx locale:

Contents:

.. toctree::
   :maxdepth: 4

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

Quindi in package1.rst, dovresti essere in grado di fare semplicemente riferimento ai pacchetti relativi normalmente.

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:

È anche possibile configurare sphinx per avere solo il file index.rst nella root e tutte le altre cose di sphinx in Project / docs:

Per Windows ho spostato tutti i file e le directory sphinx (eccetto index.rst) in docs / e ho cambiato:

docs/make.bat: Modificare

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

per

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

docs/conf.py: Inserisci

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

Ho risolto il mio problema abbastanza simile con la differenza che volevo includere un notebook jupyter esterno. Avevo installato nbsphinx ma non riuscivo a farlo funzionare. Cosa non ha funzionato:

1. Avevo la directory che volevo includere la radice nel percorso:

   conf.py:

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

2. L'uso del .. include:: directivefile è stato incluso nella documentazione ma così com'è.

Infine, ciò che ha risolto il problema è stata l'installazione del pacchetto nbsphinx-link

Una soluzione, se è davvero impossibile utilizzare collegamenti relativi di backup, ../è che potrei usare shutilper copiare i file nell'albero delle cartelle conf.pydelle specifiche nella specifica, ma preferirei non avere più copie a meno che non sia assolutamente necessario.