O sphinx pode vincular a documentos que não estão localizados em diretórios abaixo do documento raiz?

Estou usando o Sphinx para documentar um projeto não Python. Desejo distribuir ./docpastas em cada submódulo, contendo submodule_name.rstarquivos para documentar aquele módulo. Em seguida, quero sugar esses arquivos para a hierarquia mestre para criar uma especificação para todo o design.

Ie:

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

Tentei incluir arquivos no project_spec.rstdocumento mestre para a árvore assim:

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

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

No entanto, essa mensagem de erro resulta:

AVISO: toctree contém referência a documento não existente u'modules / module1 / docs / module1 '

Não é possível usar ../em um caminho de documento de alguma forma?

Atualização: Adicionado local conf.py

Atualização: Além do truque de inclusão abaixo, isso ainda (2019) não é possível. Há um problema aberto que continua sendo levado adiante: https://github.com/sphinx-doc/sphinx/issues/701

Sim você pode!

No lugar de um link simbólico (que não funciona no Windows), crie um documento stub que não contenha nada além de uma .. include::diretiva.

Corri para isso tentando vincular a um arquivo README que estava no topo da árvore de origem. Coloquei o seguinte em um arquivo chamado readme_link.rst:

.. include:: ../README

Em seguida index.rst, fiz a árvore toc parecer:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

E agora eu tenho um link para minhas notas de lançamento na minha página de índice.

Agradecimentos a http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html pela sugestão

Parece que a resposta é não, os documentos listados na árvore toc devem residir no diretório de origem , ou seja, o diretório que contém seu documento mestre e conf.py(e quaisquer subdiretórios).

Da lista de e-mails sphinx-dev :

Na STScI, escrevemos documentação para projetos individuais no Sphinx e, em seguida, também produzimos um "documento mestre" que inclui (usando toctree) vários desses outros documentos específicos do projeto. Para fazer isso, criamos links simbólicos no diretório de origem de doc do documento mestre para os diretórios de origem de doc dos projetos, uma vez que toctree realmente não parece querer incluir arquivos fora da árvore de origem de doc.

Portanto, em vez de copiar os arquivos usando, shutilvocê pode tentar adicionar links simbólicos para todos os seus módulos no Project/docs/specdiretório. Se você criar um link simbólico para Project/modulesvocê, fará referência a esses arquivos em sua árvore de toque simplesmente como modules/module1/docs/module1etc.

Em conf.py, adicione os caminhos relativos ao sistema usando sys.path e os.path

Por exemplo:

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

Em seguida, use seu index.rst como de costume, referenciando os primeiros arquivos no mesmo diretório. Então, em meu index.rst em minha pasta local Sphinx:

Contents:

.. toctree::
   :maxdepth: 4

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

Em seguida, em package1.rst, você deve ser capaz de apenas referenciar os pacotes relativos normalmente.

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:

Também é possível configurar o sphinx para ter apenas o arquivo index.rst na raiz e todas as outras coisas do sphinx em Project / docs:

Para o Windows, movi todos os arquivos e dirs sphinx (exceto index.rst) para docs / e alterei:

docs/make.bat: Mudança

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

para

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

docs/conf.py: Adicionar

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

Resolvi meu problema bastante semelhante com a diferença que queria incluir um notebook jupyter externo. Eu tinha instalado o nbsphinx, mas não conseguia fazê-lo funcionar. O que não funcionou:

1. Eu tinha o diretório que queria incluir a raiz no caminho:

   conf.py:

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

2. Usando o, .. include:: directiveo arquivo foi incluído na documentação, mas como está.

Finalmente, o que resolveu o problema foi instalar o pacote nbsphinx-link

Uma solução, se for realmente impossível usar links relativos de backup, ../é que eu poderia usar shutilpara copiar os arquivos para a árvore de pastas de especificações no conf.pyfor the spec, mas prefiro não ter várias cópias, a menos que seja absolutamente necessário.