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

Oui, c'est possible !

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

J'ai rencontré ce problème en essayant de créer un lien vers un fichier README qui se trouvait au sommet de l'arborescence des sources. J'ai mis ce qui suit dans un fichier appelé readme_link.rst :

.. include:: ../README

Ensuite, dans index.rst J'ai fait en sorte que l'arborescence ressemble à ce qui suit :

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

Answer 2

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

A partir de la liste de diffusion sphinx-dev :

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

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

Answer 3

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 faisant référence aux fichiers rst dans le même répertoire. Ainsi, mon index.rst se trouve 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 référencer les paquets 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:

Answer 4

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

1. J'avais le répertoire dans lequel je voulais inclure la racine dans le chemin d'accès :

   conf.py :

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

2. L'utilisation de la .. include:: directive le fichier était inclus dans la documentation mais tel quel.

Enfin quoi résolu le problème était l'installation du paquet nbsphinx-link

Answer 5

Ma réponse est essentiellement celle de @Dan Menes, mais pour Myst parser au lieu de reStructured.

Je préférerais ajouter ceci en tant que commentaire à la réponse de @Dan Menes, car elle y a sa place, mais les commentaires ne me permettent pas de faire le formatage, la syntaxe Myst est sensible aux nouvelles lignes et les commentaires sont limités en caractères. Je le poste donc comme une réponse séparée, même s'il est lié à une réponse existante.

Pour l'inclure dans le Myst, il faut le formater légèrement différemment :

```{include} ../main/post_installation_windows.md
```

Il peut se charger lui-même du balisage reStructured (le fichier inclus sera alors traité comme s'il avait été écrit en restructured) :

```{eval-rst}
.. include:: snippets/include-rst.rst
```

Toutefois, il est plus facile d'utiliser la syntaxe native de Myst. Par exemple, l'inclusion d'un fichier ne résoudra pas correctement les références à l'intérieur du fichier inclus, alors que l'inclusion littérale devrait le faire :

```{include-literal} ../../example.md
:language: md
```

Il se peut que vous découvriez que l'inclusion d'un document simple est acceptable, mais que l'inclusion d'un document complexe avec de nombreuses références vous causera plus de maux de tête, c'est pourquoi je recommanderais la méthode expérimentale suivante include-literal (à partir de la version 0.12.7)

Référence : https://myst-parser.readthedocs.io/en/latest/using/howto.html