Sphinx có thể liên kết đến các tài liệu không nằm trong thư mục bên dưới tài liệu gốc không?

Question 1

Tôi đang sử dụng Sphinx để ghi lại một dự án không phải Python. Tôi muốn phân phối ./doccác thư mục trong mỗi mô-đun con, chứa submodule_name.rstcác tệp để ghi lại mô-đun đó. Sau đó, tôi muốn đưa các tệp đó vào hệ thống phân cấp chính để tạo thông số kỹ thuật cho toàn bộ thiết kế.

I E:

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

Tôi đã cố gắng đưa các tệp vào bộ project_spec.rsttài liệu chính như thế này:

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

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

Tuy nhiên, thông báo lỗi này dẫn đến:

CẢNH BÁO: toctree chứa tham chiếu đến tài liệu không tồn tại u'modules / module1 / docs / module1 '

Có phải nó không thể sử dụng ../trong một đường dẫn tài liệu bằng cách nào đó không?

Cập nhật: Đã thêm địa điểm conf.py

Cập nhật: Ngoài thủ thuật bao gồm bên dưới, điều này vẫn (2019) không thể thực hiện được. Có một sự cố mở tiếp tục được đẩy lên: https://github.com/sphinx-doc/sphinx/issues/701

Question 2

Có, bạn có thể!

Thay cho một liên kết tượng trưng (sẽ không hoạt động trên Windows), hãy tạo một tài liệu sơ khai không có gì trong đó ngoài một .. include::chỉ thị.

Tôi đã gặp phải vấn đề này khi cố gắng liên kết đến một tệp README ở trên cùng của cây nguồn. Tôi đặt những thứ sau vào một tệp có tên readme_link.rst:

.. include:: ../README

Sau đó index.rst, tôi làm cho cây toctree trông giống như:

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

Và bây giờ tôi có một liên kết đến ghi chú phát hành của tôi trên trang chỉ mục của tôi.

Cảm ơn http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html cho đề xuất

Question 3

Có vẻ như câu trả lời là không, các tài liệu được liệt kê trong toc-tree phải nằm trong thư mục nguồn , tức là thư mục chứa tài liệu chính của bạn và conf.py(và bất kỳ thư mục con nào).

Từ danh sách gửi thư sphinx-dev :

Tại STScI, chúng tôi viết tài liệu cho các dự án riêng lẻ trong Sphinx, và sau đó cũng tạo ra một "tài liệu tổng thể" bao gồm (sử dụng toctree) một số tài liệu dành riêng cho dự án này. Để thực hiện việc này, chúng tôi tạo các liên kết tượng trưng trong thư mục nguồn doc của tài liệu chính tới các thư mục nguồn doc của dự án, vì toctree thực sự dường như không muốn bao gồm các tệp bên ngoài cây nguồn doc.

Vì vậy, thay vì sao chép tệp bằng cách sử dụng, shutilbạn có thể thử thêm các liên kết tượng trưng vào tất cả các mô-đun của mình trong Project/docs/specthư mục. Nếu bạn tạo một liên kết biểu tượng cho Project/modulesbạn, thì bạn sẽ tham chiếu các tệp này trong cây tốc độ của bạn đơn giản làmodules/module1/docs/module1 v.v.

Question 4

Trong conf.py, thêm các đường dẫn tương đối vào hệ thống bằng cách sử dụng sys.path và os.path

Ví dụ:

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

Sau đó, sử dụng index.rst của bạn như bình thường, tham chiếu đến các tệp đầu tiên trong cùng một thư mục. Vì vậy, trong index.rst của tôi trong thư mục Sphinx cục bộ của tôi:

Contents:

.. toctree::
   :maxdepth: 4

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

Sau đó, trong package1.rst, bạn sẽ có thể chỉ tham chiếu các gói tương đối một cách bình thường.

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:

Question 5

Cũng có thể cấu hình sphinx để chỉ có tệp index.rst trong thư mục gốc và tất cả những thứ khác về sphinx trong Project / docs:

Đối với windows, tôi đã chuyển tất cả các tệp và dirs nhân sư (ngoại trừ index.rst) vào docs / và đã thay đổi:

docs/make.bat: Thay đổi

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

đến

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

docs/conf.py: Thêm vào

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

Question 6

Tôi đã giải quyết vấn đề tương tự của mình với sự khác biệt mà tôi muốn bao gồm một sổ ghi chép jupyter bên ngoài. Tôi đã cài đặt nbsphinx nhưng không thể làm cho nó hoạt động. Những gì không hoạt động:

Tôi đã có thư mục mà tôi muốn đưa thư mục gốc vào đường dẫn:

conf.py:

import os import sys sys.path.insert(...
Sử dụng .. include:: directivetệp đã được bao gồm trong tài liệu nhưng hiện tại.

Cuối cùng, những gì đã giải quyết vấn đề là cài đặt gói nbsphinx-link

Question 7

Một giải pháp, nếu thực sự không thể sử dụng các liên kết tương đối sao lưu ../là tôi có thể sử dụng shutilđể sao chép các tệp vào cây thư mục spec trong conf.pyspec, nhưng tôi không muốn có nhiều bản sao trừ khi thực sự cần thiết.