Dapatkah sphinx menautkan ke dokumen yang tidak terletak di direktori di bawah dokumen root?

Saya menggunakan Sphinx untuk mendokumentasikan proyek non-Python. Saya ingin mendistribusikan ./docfolder di setiap submodule, berisi submodule_name.rstfile untuk mendokumentasikan modul itu. Saya kemudian ingin memasukkan file-file itu ke dalam hierarki master untuk membuat spesifikasi untuk keseluruhan desain.

Yaitu:

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

Saya mencoba memasukkan file dalam project_spec.rstdokumen master toctree seperti ini:

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

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

Namun pesan kesalahan ini menghasilkan:

PERINGATAN: toctree berisi referensi ke dokumen yang tidak ada u'modules / module1 / docs / module1 '

Apakah tidak mungkin untuk digunakan ../dalam jalur dokumen entah bagaimana?

Pembaruan: Menambahkan lokasi conf.py

Pembaruan: Selain trik sertakan di bawah ini, ini masih (2019) tidak memungkinkan. Ada masalah terbuka yang terus dimajukan: https://github.com/sphinx-doc/sphinx/issues/701

Ya kamu bisa!

Sebagai pengganti symlink (yang tidak akan berfungsi di Windows), buat dokumen rintisan yang tidak memiliki apa pun di dalamnya selain .. include::arahan.

Saya mengalami ini mencoba untuk menautkan ke file README yang ada di atas pohon sumber. Saya meletakkan yang berikut ini dalam sebuah file bernama readme_link.rst:

.. include:: ../README

Kemudian index.rst, saya membuat toctree terlihat seperti:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

Dan sekarang saya memiliki link ke catatan rilis saya di halaman indeks saya.

Terima kasih kepada http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html atas sarannya

Tampaknya jawabannya adalah tidak, dokumen yang terdaftar di pohon-toc harus berada di dalam direktori sumber , yaitu direktori yang berisi dokumen master Anda dan conf.py(dan subdirektori lainnya).

Dari milis sphinx-dev :

Di STScI, kami menulis dokumentasi untuk masing-masing proyek di Sphinx, dan kemudian juga menghasilkan "dokumen master" yang mencakup (menggunakan toctree) sejumlah dokumen khusus proyek lainnya. Untuk melakukan ini, kami membuat symlink di direktori sumber dokumen master ke direktori sumber dokumen proyek, karena toctree sepertinya tidak benar-benar ingin menyertakan file di luar pohon sumber doc.

Jadi daripada menyalin file menggunakan shutilAnda bisa mencoba menambahkan symlink ke semua modul Anda di Project/docs/specdirektori. Jika Anda membuat symlink ke Project/modulesAnda maka akan mereferensikan file-file ini di toc-tree Anda hanya sebagai modules/module1/docs/module1dll.

Di conf.py, tambahkan jalur relatif ke sistem menggunakan sys.path dan os.path

Sebagai contoh:

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

Kemudian gunakan index.rst Anda seperti biasa, dengan mereferensikan file pertama di direktori yang sama. Jadi di index.rst saya di folder Sphinx lokal saya:

Contents:

.. toctree::
   :maxdepth: 4

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

Kemudian di package1.rst, Anda seharusnya dapat mereferensikan paket relatif secara normal.

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:

Anda juga dapat mengkonfigurasi sphinx agar hanya memiliki file index.rst di root dan semua hal sphinx lainnya di Project / docs:

Untuk windows saya memindahkan semua file sphinx dan dirs (kecuali index.rst) ke docs / dan mengubah:

docs/make.bat: Ubah

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

untuk

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

docs/conf.py: Menambahkan

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

Saya memecahkan masalah saya yang sangat mirip dengan perbedaan yang saya inginkan untuk menyertakan notebook jupyter eksternal. Saya telah menginstal nbsphinx tetapi saya tidak dapat membuatnya berfungsi. Apa yang tidak berhasil:

1. Saya memiliki direktori yang ingin saya sertakan root di jalur:

   conf.py:

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

2. Menggunakan .. include:: directivefile tersebut disertakan dalam dokumentasi tetapi apa adanya.

Akhirnya yang menyelesaikan masalah adalah menginstal paket nbsphinx-link

Satu solusi, jika benar-benar tidak mungkin untuk menggunakan tautan relatif yang dicadangkan ../adalah yang dapat saya gunakan shutiluntuk menyalin file ke pohon folder spesifikasi di conf.pyuntuk spesifikasi, tetapi saya lebih suka tidak memiliki banyak salinan kecuali benar-benar diperlukan.