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

90

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

mc_electron
fonte
Você precisa adicionar o .rstramal à linha Module 1 <../../modules/module1/docs/module1>?
Chris de
Acho que não porque no Sphinx Docs : Como os arquivos de origem do reST podem ter extensões diferentes (algumas pessoas gostam de .txt, outras como .rst - a extensão pode ser configurada com source_suffix) e diferentes sistemas operacionais têm diferentes separadores de caminho, Sphinx os abstrai: todos os “nomes de documentos” são relativos ao diretório de origem, a extensão é removida e os separadores de caminho são convertidos em barras.
mc_electron
OK, só um palpite! Portanto, presumo que source_suffixesteja definido como .rstem seu conf.pyarquivo de configuração. Além disso, onde está esse arquivo em sua hierarquia de diretório, uma vez que parece que todos os caminhos são relativos a esse arquivo?
Chris de
Sim, source_suffixestá definido como .rste conf.pyestá na mesma pasta que o project_spec.rstarquivo.
mc_electron de

Respostas:

108

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

Dan Menes
fonte
5
Se o README tiver imagens ou similares com caminhos relativos que não são válidos dentro do diretório index.rst, como você lida com isso? Recebo erros de 'arquivo de imagem não legível'.
Lucas W
Sim, você também pode fazer isso no Unix com links simbólicos. Você pode criar um link com o mesmo nome da pasta docs (ou seja docs) que se vincula a current-dir ('.'). Então você pode usar: download: docs\foo.rste isso funcionaria para docsarquivos dentro da pasta ou de seu pai.
ankostis
1
Acabei de voltar aqui e aceitei esta resposta, obrigado! Não tenho certeza sobre as imagens, mas você sempre pode copiá-las no conf.py.
mc_electron
11
Eu precisava usar .. include:: ../readme.rstincluindo a extensão.
nu everest
1
Para incluir apenas parte do README.rst: muffinresearch.co.uk/…
ederag
14

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.

Chris
fonte
3
Isso é ruim. Uma das vantagens que vejo ao tentar mudar dos documentos do Word para o Sphinx é que você pode importar um módulo de hardware reutilizável para o seu projeto e apenas incluir sua documentação na documentação principal do design. Eu usaria links simbólicos, mas, infelizmente, estou no windows.
mc_electron
Para a posteridade, tentei adicionar a pasta doc do submódulo ao sys.patharquivo conf.py, mas não funcionou.
mc_electron
1
@mc_electron Para links simbólicos no Windows, use o comando mklink.
Jeremy
11

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:
Um Kingscote
fonte
Este é um novo comportamento? Em qual versão foi adicionado?
mc_electron
2
Seria ótimo se descrito com mais detalhes para informar os iniciantes. Por exemplo, o que é Package1? Isso é pathespecificado primeiro usando sys.path.insert? Ou existe um tutorial em algum lugar? Não consigo encontrar o documento relevante.
Manavalan Gajapathy
Package1é uma entrada nomeada para que o sumário mostre "Pacote1" como o título da seção.
PabloC
2
Isso permite que você faça o autodoc dos módulos Python em outro diretório, mas não permite que você inclua arquivos RST em outro diretório.
mc_electron
1

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('..'))
mrtnlrsn
fonte
Obrigado! Essa configuração funciona muito bem para mim quando tenho vários pacotes relacionados em um repositório, referenciados na mesma documentação.
Gregor Müllegger
1

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

DesperateEngineer
fonte
0

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.

mc_electron
fonte