Sphinx, kök belgenin altındaki dizinlerde bulunmayan belgelere bağlanabilir mi?

Python dışı bir projeyi belgelemek için Sphinx kullanıyorum. ./docHer alt modülde, submodule_name.rstbu modülü belgelemek için dosyalar içeren klasörleri dağıtmak istiyorum . Daha sonra tüm tasarım için bir özellik oluşturmak için bu dosyaları ana hiyerarşiye çekmek istiyorum.

Yani:

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

Dosyaları ana project_spec.rstbelgeye şu şekilde dahil etmeye çalıştım:

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

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

Ancak bu hata mesajı:

UYARI: toctree, mevcut olmayan belgeye referans içerir u'modules / module1 / docs / module1 '

../Bir belge yolunda bir şekilde kullanmak mümkün değil mi?

Güncelleme: conf.py konumu eklendi

Güncelleme: Aşağıdaki dahil etme hilesi dışında, bu hala (2019) mümkün değil. İlerlemeye devam eden açık bir sorun var: https://github.com/sphinx-doc/sphinx/issues/701

Evet yapabilirsin!

Bir sembolik bağlantı (Windows'ta çalışmaz) yerine, bir .. include::yönergeden başka hiçbir şey içermeyen bir saplama belgesi oluşturun .

Kaynak ağacının tepesindeki bir README dosyasına bağlanmaya çalışırken bununla karşılaştım. Aşağıdakileri adlı bir dosyaya koydum readme_link.rst:

.. include:: ../README

Sonra index.rst, toctree'nin şöyle görünmesini sağladım:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

Ve şimdi dizin sayfamda sürüm notlarıma bir bağlantı var.

Öneri için http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html'ye teşekkürler

Görünüşe göre cevap hayır, toc ağacında listelenen belgeler kaynak dizinde , yani ana belgenizi ve conf.py(ve herhangi bir alt dizini) içeren dizinde yer almalıdır .

Gönderen sfenks-dev posta listesine :

STScI'de, Sphinx'teki bireysel projeler için dokümantasyon yazıyoruz ve ardından bu diğer projeye özgü dokümanların bir kısmını içeren (toctree kullanarak) bir "ana doküman" üretiyoruz. Bunu yapmak için, ana belgenin doc kaynak dizininde projelerin belge kaynak dizinlerine sembolik bağlar oluşturuyoruz, çünkü toctree gerçekten de belge kaynak ağacının dışındaki dosyaları dahil etmek istemiyor gibi görünüyor.

Bu nedenle, dosyaları kullanarak kopyalamak yerine shutil, Project/docs/specdizindeki tüm modüllerinize sembolik bağlantılar eklemeyi deneyebilirsiniz . Size bir sembolik bağlantı oluşturursanız, Project/modulesbu dosyalara toc ağacınızda basitçe modules/module1/docs/module1vb.

Conf.py'de, sys.path ve os.path kullanarak sisteme göreli yolları ekleyin

Örneğin:

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

Daha sonra, aynı dizindeki ilk dosyalara başvurarak her zamanki gibi index.rst dosyanızı kullanın. Yerel Sphinx klasörümdeki index.rst dosyamda:

Contents:

.. toctree::
   :maxdepth: 4

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

Daha sonra package1.rst'de, sadece göreceli paketlere normal olarak başvurabilmelisiniz.

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:

Sphinx'i yalnızca index.rst dosyasını kökte ve diğer tüm sfenks öğelerini Project / docs'da olacak şekilde yapılandırmak da mümkündür:

Windows için tüm sphinx dosyalarını ve dizinlerini (index.rst hariç) docs / içine taşıdım ve değiştirdim:

docs/make.bat: Değişiklik

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

-e

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

docs/conf.py: Ekle

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

Oldukça benzer problemimi harici bir jupyter not defteri eklemek istediğim farkla çözdüm. Nbsphinx'i kurmuştum ama çalışmasını sağlayamadım. Ne işe yaramadı:

1. Kökü yola dahil etmek istediğim dizine sahiptim:

   conf.py:

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

2. .. include:: directiveDosyayı kullanmak belgelere dahil edildi, ancak olduğu gibi.

Sonunda sorunu çözen , nbsphinx-link paketini kurmaktı

Bir çözüm, yedeklenen göreceli bağlantıları kullanmak gerçekten imkansızsa , dosyaları spesifikasyondaki spesifikasyon klasör ağacına kopyalamak için ../kullanabilmemdir , ancak kesinlikle gerekli olmadıkça birden fazla kopyaya sahip olmamayı tercih ederim.shutilconf.py