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?


90

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


Avez-vous besoin d'ajouter l' .rstextension à la ligne Module 1 <../../modules/module1/docs/module1>?
Chris

Je ne pense pas parce que dans les documents Sphinx : puisque les fichiers source reST peuvent avoir différentes extensions (certaines personnes comme .txt, d'autres comme .rst - l'extension peut être configurée avec source_suffix) et différents systèmes d'exploitation ont des séparateurs de chemin différents, Sphinx les résume: tous les «noms de document» sont relatifs au répertoire source, l'extension est supprimée et les séparateurs de chemin sont convertis en barres obliques.
mc_electron

OK, juste une supposition! Je suppose donc que cela source_suffixest défini .rstdans votre conf.pyfichier de configuration. De plus, où se trouve ce fichier dans votre hiérarchie de répertoires, car il semble que tous les chemins soient relatifs à ce fichier?
Chris

Oui, source_suffixest défini sur .rstet conf.pyest dans le même dossier que le project_spec.rstfichier.
mc_electron

Réponses:


108

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


5
Si le README contient des images ou similaires qui ont des chemins relatifs qui ne sont pas valides dans le répertoire index.rst se trouve, comment le gérez-vous? J'obtiens des erreurs «fichier image non lisible».
Lucas W

Oui, vous pouvez également le faire sous Unix avec des liens symboliques. Vous pouvez créer un lien avec le même nom que le dossier docs (c.-à-d. docs) Qui renvoie au répertoire courant ('.'). Ensuite, vous pouvez utiliser: download: docs\foo.rstet cela fonctionnerait pour les fichiers dans le docsdossier ou son parent.
ankostis

1
Je viens de finir ici et j'ai accepté cette réponse, merci! Je ne suis pas sûr des images, mais vous pouvez toujours les copier dans le fichier conf.py.
mc_electron

11
J'avais besoin d'utiliser .. include:: ../readme.rstnotamment l'extension.
nu everest

1
Pour n'inclure qu'une partie du fichier README.rst: muffinresearch.co.uk/…
ederag

14

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.


3
C'est dommage. L'un des avantages que je vois en essayant de passer des documents Word à Sphinx est que vous pouvez importer un module matériel réutilisable dans votre projet et simplement inclure sa documentation dans la documentation principale de la conception. J'utiliserais des liens symboliques mais hélas je suis sous Windows.
mc_electron

Pour la postérité, j'ai essayé d'ajouter le dossier doc du sous-module au sys.pathdans le conf.py mais cela n'a pas fonctionné.
mc_electron

1
@mc_electron Pour les liens symboliques sous Windows, utilisez la commande mklink.
Jeremy

11

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:

Est-ce nouveau comportement? Dans quelle version a-t-il été ajouté?
mc_electron

2
Ce serait génial si décrit plus en détail pour informer les débutants. Par exemple, qu'est-ce que c'est Package1? Est-ce que c'est d'abord pathspécifié en utilisant sys.path.insert? Ou, y a-t-il un tutoriel quelque part? Je n'arrive pas à trouver le document pertinent.
Manavalan Gajapathy

Package1est une entrée nommée de sorte que la table des matières affiche "Package1" comme titre de la section.
PabloC

2
Cela vous permet d'autodocaliser les modules Python dans un autre répertoire, mais cela ne vous permet pas d'inclure des fichiers RST dans un autre répertoire.
mc_electron

1

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

Merci! Cette configuration fonctionne très bien pour moi lorsque j'ai plusieurs packages associés dans un référentiel, référencés à partir de la même documentation.
Gregor Müllegger

1

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


0

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.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.