สฟิงซ์สามารถเชื่อมโยงไปยังเอกสารที่ไม่อยู่ในไดเร็กทอรีด้านล่างของเอกสารรูทได้หรือไม่?

ฉันใช้ Sphinx เพื่อจัดทำเอกสารโครงการที่ไม่ใช่ Python ฉันต้องการกระจาย./docโฟลเดอร์ในแต่ละโมดูลย่อยที่มีsubmodule_name.rstไฟล์เพื่อจัดทำเอกสารโมดูลนั้น จากนั้นฉันต้องการดูดไฟล์เหล่านั้นลงในลำดับชั้นหลักเพื่อสร้างข้อมูลจำเพาะสำหรับการออกแบบทั้งหมด

ได้แก่ :

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

ฉันพยายามรวมไฟล์ในโททรีproject_spec.rstเอกสารหลักดังนี้:

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

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

อย่างไรก็ตามผลลัพธ์ของข้อความแสดงข้อผิดพลาดนี้:

คำเตือน: toctree มีการอ้างอิงถึงเอกสารที่ไม่มีอยู่ u'modules / module1 / docs / module1 '

ไม่สามารถใช้../ในเส้นทางเอกสารได้หรือไม่?

อัปเดต: เพิ่มตำแหน่ง conf.py

อัปเดต: นอกเหนือจากเคล็ดลับรวมด้านล่างนี้ยังเป็นไปไม่ได้ (2019) มีปัญหาที่เปิดอยู่ซึ่งได้รับการผลักดันไปข้างหน้า: https://github.com/sphinx-doc/sphinx/issues/701

ใช่คุณสามารถ!

แทน symlink (ซึ่งใช้ไม่ได้กับ Windows) ให้สร้างเอกสาร Stub ที่ไม่มีอะไรเลยนอกจาก.. include::คำสั่ง

ฉันพบสิ่งนี้โดยพยายามเชื่อมโยงไปยังไฟล์ README ที่อยู่ด้านบนสุดของแผนผังซอร์ส ฉันใส่สิ่งต่อไปนี้ในไฟล์ชื่อreadme_link.rst:

.. include:: ../README

จากนั้นindex.rstฉันทำให้ toctree ดูเหมือน:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

และตอนนี้ฉันมีลิงก์ไปยังบันทึกประจำรุ่นของฉันในหน้าดัชนีของฉัน

ขอบคุณhttp://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.htmlสำหรับข้อเสนอแนะ

ดูเหมือนว่าคำตอบคือไม่เอกสารที่อยู่ใน toc-tree จะต้องอยู่ในไดเร็กทอรีต้นทางนั่นคือไดเร็กทอรีที่มีเอกสารหลักของคุณและconf.py(และไดเร็กทอรีย่อยใด ๆ )

จากรายชื่อผู้รับจดหมาย sphinx-dev :

ที่ STScI เราเขียนเอกสารสำหรับแต่ละโครงการใน Sphinx จากนั้นก็จัดทำ "เอกสารหลัก" ซึ่งรวมถึง (ใช้ toctree) เอกสารเฉพาะโครงการอื่น ๆ อีกจำนวนหนึ่ง ในการทำเช่นนี้เราจะสร้าง symlinks ในไดเร็กทอรีต้นทาง doc ของเอกสารหลักไปยังไดเร็กทอรีต้นทาง doc ของโปรเจ็กต์เนื่องจาก toctree ดูเหมือนจะไม่ต้องการรวมไฟล์นอกแผนผังซอร์สของ doc

ดังนั้นแทนที่จะคัดลอกไฟล์โดยใช้shutilคุณสามารถลองเพิ่ม symlink ให้กับโมดูลทั้งหมดของคุณในProject/docs/specไดเร็กทอรี หากคุณสร้าง symlink ให้Project/modulesคุณจะอ้างอิงไฟล์เหล่านี้ใน toc-tree ของคุณเช่นเดียวกับmodules/module1/docs/module1อื่น ๆ

ใน conf.py เพิ่มพา ธ สัมพัทธ์ไปยังระบบโดยใช้ sys.path และ os.path

ตัวอย่างเช่น:

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

จากนั้นใช้ index.rst ของคุณตามปกติโดยอ้างอิงไฟล์ rst ในไดเร็กทอรีเดียวกัน ดังนั้นใน index.rst ของฉันในโฟลเดอร์ Sphinx ในเครื่องของฉัน:

Contents:

.. toctree::
   :maxdepth: 4

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

จากนั้นใน package1.rst คุณควรจะอ้างอิงแพ็คเกจสัมพัทธ์ได้ตามปกติ

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:

นอกจากนี้ยังสามารถกำหนดค่าสฟิงซ์ให้มีเฉพาะไฟล์ index.rst ในรูทและเนื้อหาสฟิงซ์อื่น ๆ ทั้งหมดใน Project / docs:

สำหรับ windows ฉันย้ายไฟล์สฟิงซ์และ dirs ทั้งหมด (ยกเว้น index.rst) ไปยัง docs / และเปลี่ยน:

docs/make.bat: เปลี่ยน

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

ถึง

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

docs/conf.py: เพิ่ม

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

ฉันแก้ไขปัญหาที่ค่อนข้างคล้ายกันของฉันด้วยความแตกต่างที่ฉันต้องการรวมสมุดบันทึก jupyter ภายนอก ฉันติดตั้ง nbsphinx แล้ว แต่ไม่สามารถใช้งานได้ อะไรไม่ได้ผล:

1. ฉันมีไดเร็กทอรีที่ฉันต้องการรวมรูทในพา ธ :

   conf.py:

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

2. การใช้.. include:: directiveไฟล์นั้นรวมอยู่ในเอกสาร แต่ตามที่เป็นอยู่

ในที่สุดสิ่งที่แก้ปัญหาได้คือการติดตั้งแพ็คเกจnbsphinx-link

วิธีแก้ปัญหาหนึ่งหากเป็นไปไม่ได้จริงๆที่จะใช้ลิงก์สัมพัทธ์ที่สำรองไว้../คือฉันสามารถใช้shutilเพื่อคัดลอกไฟล์ลงในโครงสร้างโฟลเดอร์ข้อมูลจำเพาะในconf.pyข้อมูลจำเพาะได้ แต่ฉันไม่อยากมีสำเนาหลายชุดเว้นแต่จำเป็นจริงๆ