Est-ce que sphinx peut 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 souhaite distribuer des ./docdossiers dans chaque sous-module, contenant des submodule_name.rstfichiers pour documenter ce module. Je veux ensuite aspirer ces fichiers dans la hiérarchie principale pour créer une spécification pour l'ensemble de la conception.

C'est à dire:

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

J'ai essayé d'inclure des fichiers dans le project_spec.rsttoctree du document maître comme ceci:

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

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

Cependant, ce message d'erreur se produit:

ATTENTION: toctree contient une référence à un document non existant u'modules / module1 / docs / module1 '

N'est-il pas possible d'utiliser ../d'une manière ou d'une autre dans un chemin de document?

Mise à jour: ajout de l'emplacement conf.py

Mise à jour: autre que l'astuce d'inclusion ci-dessous, cela 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

Oui, vous pouvez!

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

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

.. include:: ../README

Ensuite 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 publication sur ma page d'index.

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

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

Depuis la liste de diffusion sphinx-dev :

Chez STScI, nous rédigeons la documentation pour des projets individuels dans Sphinx, puis produisons également un «document maître» qui comprend (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 doc du document maître vers les répertoires source doc des projets, car toctree ne semble vraiment pas vouloir inclure des fichiers en dehors de l'arborescence source doc.

Ainsi, plutôt que de copier des fichiers en utilisant, shutilvous pouvez essayer d'ajouter des liens symboliques vers tous vos modules dans le Project/docs/specrépertoire. Si vous créez un lien symbolique vers Project/modulesvous, alors référencer ces fichiers dans votre toc-tree simplement comme modules/module1/docs/module1etc.

Dans conf.py, ajoutez les chemins relatifs au système en utilisant 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:

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

Pour Windows, j'ai déplacé tous les fichiers et répertoires sphinx (sauf index.rst) dans docs / et j'ai 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('..'))

J'ai résolu mon problème assez similaire avec la différence que je voulais inclure un ordinateur portable jupyter externe. J'avais installé nbsphinx mais je ne pouvais pas le faire fonctionner. Ce qui n'a pas fonctionné:

1. J'avais le répertoire que je voulais inclure la racine dans le chemin:

   conf.py:

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

2. L'utilisation du .. include:: directivefichier était incluse dans la documentation mais telle quelle.

Enfin, ce qui a résolu le problème a été l'installation du paquet nbsphinx-link

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