Può sfingi link a documenti che non si trovano nelle directory sotto il documento di root?

Question

Sto usando Sphinx per documentare un progetto non Python. Voglio distribuire le cartelle ./doc in ogni sottomodulo, contenente i file submodule_name.rst per documentare quel modulo. Quindi voglio succhiare quei file nella gerarchia principale per creare una specifica per l'intero progetto.

Ie:

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

ho cercato di includere i file nel documento toctree maestro project_spec.rst come questo:

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

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

Tuttavia questo errore messaggio Risultati:

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

Non è possibile utilizzare in qualche modo il documento ../?

Aggiornamento: Aggiunto posizione conf.py

Answer 1

Sì, è possibile!

Al posto di un collegamento simbolico (che non funziona su Windows), creare un documento stub che non contiene nulla ma una direttiva .. include::.

Mi sono imbattuto in questo tentativo di collegamento a un file README che si trovava nella parte superiore dell'albero dei sorgenti.Ho messo il seguente in un file chiamato readme_link.rst:

.. include:: ../README 

Poi nel index.rst, ho fatto il toctree simile:

Contents: 

.. toctree:: 
    :maxdepth: 2 

    readme_link 
    other_stuff 

E ora ho un link al mio note di rilascio sulla mia pagina di indice.

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

Answer 2

Una soluzione, se è davvero impossibile utilizzare i collegamenti relativi che eseguono il backup ../ è che ho potuto utilizzare shutil per copiare i file nella struttura di cartelle specifiche nel conf.py per il spec, ma preferirei non avere più copie se non assolutamente necessario.

Answer 3

Sembra che la risposta è no, i documenti elencati nella toc-albero devono risiedere all'interno del source directory, cioè la directory contenente i master document e conf.py (e tutte le sottodirectory).

Dal sphinx-dev mailing list:

A STScI, scriviamo la documentazione per i singoli progetti in Sfinge, e poi anche produrre un "documento master", che comprende (usando toctree) un certo numero di questi altri documenti specifici del progetto . Per fare questo, creiamo i link simbolici nella directory dei sorgenti dei documenti del documento master alle directory dei sorgenti dei documenti del progetto, poiché in realtà non sembra che il toctree voglia includere i file al di fuori dell'albero dei sorgenti dei documenti.

Quindi, piuttosto che la copia dei file utilizzando shutil si potrebbe provare ad aggiungere link simbolici a tutti i moduli nella directory Project/docs/spec. Se si crea un collegamento simbolico a Project/modules, si farebbe quindi riferimento a questi file nel proprio albero di toce semplicemente come modules/module1/docs/module1 ecc.

Answer 4

E 'anche possibile configurare sfinge di avere solo il file index.rst nella radice e il tutte le altre cose sfinge nel progetto/docs:

Per le finestre mi sono trasferito tutti i file Sfinge e dirs (tranne index.rst) in docs/e cambiato:

docs/make.bat: Modifica

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

a

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

docs/conf.py: Aggiungere

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

Answer 5

In conf.py, aggiungere i percorsi relativi al sistema utilizzando sys.path e os.path

Ad 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 utilizzare index.rst come al solito, facendo riferimento ai primi file nella stessa directory. Così nel mio index.rst nella mia cartella Sphinx locale:

Contents: 

.. toctree:: 
    :maxdepth: 4 

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

Poi, nel package1.rst, si dovrebbe essere in grado di fare riferimento solo i relativi pacchetti 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: