Est-ce que sphinx peut créer des liens vers des documents qui ne se trouvent pas dans des répertoires situés sous le document racine ?

Question

J'utilise Sphinx pour documenter un projet non-Python. Je souhaite distribuer ./doc dans chaque sous-module, contenant submodule_name.rst pour documenter ce module. Je souhaite ensuite aspirer ces fichiers dans la hiérarchie principale afin de 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 tenté d'inclure des fichiers dans le master project_spec.rst document toctree comme celui-ci :

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

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

Cependant, le message d'erreur suivant apparaît :

WARNING : toctree contains reference to nonexisting document u'modules/module1/docs/module1' (L'arbre contient une référence à un document inexistant)

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

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

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

Answer 1

Il est également possible de configurer sphinx de manière à ce que seul le fichier index.rst se trouve dans la racine et que tous les autres éléments de sphinx se trouvent 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 : Changer

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

à

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

docs/conf.py : Ajouter

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

Answer 2

Une autre technique, qui ne nécessite pas la création de fichiers d'attente, consiste à utiliser la fonction références absolues (en commençant par / ) dans votre toctree Root, et en fixant le répertoire source à l'ancêtre commun le plus bas lors de l'appel à sphinx-build . Exemple de présentation d'un répertoire :

/path/to/common/ancestor
├── a
│   └── foo.rst
├── b
│   ├── bar.rst
│   ├── x
│   │   └── index.rst
│   └── y
│       └── boz.rst
└── c
    └── baz.rst

Et b/x/index.rst :

.. toctree::
   /a/foo
   /b/bar
   /b/y/boz
   /c/baz

Et votre sphinx-build pourrait ressembler à ceci :

sphinx-build -c <confdir> -b html -D masterdoc=b/x/index /path/to/common/ancestor <outdir>

J'ai testé cela avec sphinx 3.0.2 .

Answer 3

Une solution, s'il est vraiment impossible d'utiliser des liens relatifs qui soutiennent ../ est que je pourrais utiliser shutil pour copier les fichiers dans l'arborescence du dossier spec dans le dossier conf.py pour les spécifications, mais je préfère ne pas avoir plusieurs copies à moins que cela ne soit absolument nécessaire.