web-dev-qa-db-fra.com

Sphinx peut-il créer un lien vers des documents qui ne se trouvent pas dans des répertoires sous le document racine?

J'utilise Sphinx pour documenter un projet non Python. Je veux distribuer ./doc dossiers dans chaque sous-module, contenant submodule_name.rst fichiers pour documenter ce module. Je veux ensuite aspirer ces fichiers dans la hiérarchie principale pour créer une spécification pour la conception entière.

C'est à dire.:

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

J'ai tenté d'inclure des fichiers dans le masque project_spec.rst document toctree comme ceci:

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

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

Cependant, ce message d'erreur entraîne:

AVERTISSEMENT: toctree contient une référence à un document inexistant u'modules/module1/docs/module1 '

N'est-il pas possible d'utiliser ../ dans un chemin de document en quelque sorte?

Mise à jour: emplacement conf.py ajouté

Mise à jour: autre que l'astuce d'inclusion ci-dessous, ce n'est toujours pas possible (2019). Il y a un problème ouvert qui ne cesse de progresser: https://github.com/sphinx-doc/sphinx/issues/701

pythonpython-sphinx
77
mc_electron

Oui, vous pouvez!

Au lieu d'un lien symbolique (qui ne fonctionnera pas sous Windows), créez un document de raccord qui ne contient rien d'autre qu'un .. include:: directive.

Je suis tombé sur cela en essayant de créer un lien vers un fichier README qui était en haut de l'arborescence source. J'ai mis ce qui suit dans un fichier appelé readme_link.rst:

.. include:: ../README

Puis dans index.rst, J'ai fait ressembler le toctree:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

Et maintenant, j'ai un lien vers mes notes de version sur ma page d'index.

Merci à http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html pour la suggestion

90
Dan Menes

Il semble que la réponse soit non, les documents répertoriés dans l'arborescence toc doivent résider dans le répertoire source , c'est-à-dire le répertoire contenant votre document maître et conf.py (et tous les sous-répertoires).

De la liste de diffusion sphinx-dev :

Chez STScI, nous écrivons de la documentation pour des projets individuels dans Sphinx, puis produisons également un "document maître" qui inclut (en utilisant toctree) un certain nombre de ces autres documents spécifiques au projet. Pour ce faire, nous créons des liens symboliques dans le répertoire source du document du document maître vers les répertoires source du projet, car toctree ne semble vraiment pas vouloir inclure de fichiers en dehors de l'arborescence des sources du document.

Donc, plutôt que de copier des fichiers à l'aide de shutil, vous pouvez essayer d'ajouter des liens symboliques à tous vos modules dans le Project/docs/spec répertoire. Si vous créez un lien symbolique vers Project/modules vous référenceriez alors ces fichiers dans votre arborescence toc simplement comme modules/module1/docs/module1 etc.

14
Chris

Dans conf.py, ajoutez les chemins relatifs au système à l'aide de sys.path et os.path

Par exemple:

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

Utilisez ensuite votre index.rst comme d'habitude, en référençant les premiers fichiers dans le même répertoire. Donc, dans mon index.rst dans mon dossier Sphinx local:

Contents:

.. toctree::
   :maxdepth: 4

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

Ensuite, dans package1.rst, vous devriez pouvoir simplement référencer les packages relatifs normalement.

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:
8
A Kingscote

Une solution, s'il est vraiment impossible d'utiliser des liens relatifs qui sauvegardent ../ est que je pouvais utiliser shutil pour copier les fichiers dans l'arborescence des dossiers dans conf.py pour la spécification, mais je préfère ne pas avoir plusieurs copies sauf si absolument nécessaire.

0
mc_electron

Il est également possible de configurer sphinx pour avoir uniquement le fichier index.rst à la racine et tous les autres éléments de sphinx dans Project/docs:

Pour Windows, j'ai déplacé tous les fichiers et répertoires sphinx (sauf index.rst) dans docs/et changé:

docs/make.bat: Changement

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

à

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

docs/conf.py: Ajouter

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