Toctree điều kiện trong Sphinx

Question

Tôi muốn thực hiện nhiều phiên bản tài liệu, khác với các phần được bao gồm. Để đạt được điều này, tôi thường sử dụng chỉ thị only hoặc tiện ích mở rộng ifconfig. Tuy nhiên, tôi không thể sử dụng bất kỳ kết hợp nào trong số đó kết hợp với chỉ thị toctree.

.. toctree:: 
    :maxdepth: 2 

    intro 
    strings 
    datatypes 
    numeric 
    .. only:: university 
     complex 

Có cách nào để làm điều đó:

một cái gì đó như thế này Những gì tôi về cơ bản muốn là?

Answer 1

Theo như tôi biết không có cách nào để làm những gì bạn muốn. Tôi đã đấu tranh với cùng một vấn đề, xem https://github.com/sphinx-doc/sphinx/issues/1717.

Lý do là Nhân sư xử lý tất cả các dòng chứa trong nút toctree dưới dạng văn bản thuần túy.

tôi thấy hai lựa chọn:

1. bạn có thể viết chỉ thị toctree của riêng bạn;

2. bạn có thể kéo dài tuổi toctree bao gồm một tùy chọn có chứa các biểu thức để được đánh giá

   .. toctree: 
       :condition: expression 
   
       file1 
   

và sau đó bạn tùy chỉnh các sự kiện doctree quyết tâm.

3. bạn có thể sử dụng thay thế văn bản trên văn bản thô xác định thẻ của riêng bạn. bạn có thể thực hiện điều đó để thực hiện một trình xử lý sự kiện cho sự kiện đọc nguồn. Ví dụ $$condition$$ có thể chứa điều kiện để được đánh giá, trong khi $$$ cuối của khối, ví dụ:

   .. toctree: 
   
       file1 
       $$mycondition$$ 
       file2 
       $$$ 
   

Tùy thuộc vào mycondition, bạn có thể loại bỏ các dòng khối tiếp theo.

Số 3 khá đơn giản, trong khi đối với tôi số 2 là thanh lịch nhất.

Answer 2

Giải pháp của tôi là đặt nội dung có điều kiện vào một thư mục riêng 'thực tập' và sử dụng thẻ 'nội bộ'.

Trong conf.py tôi đã thêm các dòng

if tags.has('internal'): 
    exclude_patters = ['_build'] 
else: 
    exclude_patterns = ['_build', 'intern*'] 

Bây giờ khi tôi vượt qua cờ 'nội bộ' trên dòng lệnh tôi nhận được tất cả, nếu không tất cả mọi thứ ngoại trừ các nội dung trong thư mục tập.

Thẻ nội bộ chỉ có thể được sử dụng kết hợp với chỉ.

ToC chứa tham chiếu đến thực tập/somedoc và chúng được bao gồm hoặc bỏ qua theo yêu cầu. Tôi nhận được một số cảnh báo về các trang bị thiếu nhưng có thể bị tắt tiếng.

Answer 3

Một giải pháp rất đơn giản là duy trì hai tệp chỉ mục riêng biệt dưới các tên khác nhau. Bạn có thể chỉ định tệp chỉ mục nào sẽ sử dụng theo mặc định trong conf.py và ghi đè tệp đó cho một công trình đặc biệt bằng cách sử dụng -D master_doc=alternate-index trên dòng lệnh sphinx-build.

Answer 4

Câu trả lời trước của tôi không thành công nếu bạn có phân cấp của bảng nội dung vì vậy tôi đã viết chỉ thị đơn giản toctree-filt có thể lọc các mục dựa trên tiền tố của mục nhập. Ví dụ, đưa ra một chỉ thị toctree-filt như

.. toctree-filt:: 
    :maxdepth: 1 

    user-manual 
    :internal:supervisor-api 
    :draft:new-feature 
    :erik:erik-maths 
    api 

và thiết lập danh sách loại trừ để ['draft','erik'] sẽ dẫn đến một toctree hiệu quả trông giống như

.. toctree-filt:: 
    :maxdepth: 1 

    user-manual 
    supervisor-api 
    api 

Thêm các dòng sau để conf.py của bạn:

sys.path.append(os.path.abspath('../sphinx-ext/')) 
extensions = ['toctree_filter'] 
toc_filter_exclude = ['draft','erik'] 

Đặt mã sau vào /sphinx_ext bên cạnhcủa bạnthư mục:

import re 
from sphinx.directives.other import TocTree 


def setup(app): 
    app.add_config_value('toc_filter_exclude', [], 'html') 
    app.add_directive('toctree-filt', TocTreeFilt) 
    return {'version': '1.0.0'} 

class TocTreeFilt(TocTree): 
    """ 
    Directive to notify Sphinx about the hierarchical structure of the docs, 
    and to include a table-of-contents like tree in the current document. This 
    version filters the entries based on a list of prefixes. We simply filter 
    the content of the directive and call the super's version of run. The 
    list of exclusions is stored in the **toc_filter_exclusion** list. Any 
    table of content entry prefixed by one of these strings will be excluded. 
    If `toc_filter_exclusion=['secret','draft']` then all toc entries of the 
    form `:secret:ultra-api` or `:draft:new-features` will be excuded from 
    the final table of contents. Entries without a prefix are always included. 
    """ 
    hasPat = re.compile('^\s*:(.+):(.+)$') 

    # Remove any entries in the content that we dont want and strip 
    # out any filter prefixes that we want but obviously don't want the 
    # prefix to mess up the file name. 
    def filter_entries(self, entries): 
     excl = self.state.document.settings.env.config.toc_filter_exclude 
     filtered = [] 
     for e in entries: 
      m = self.hasPat.match(e) 
      if m != None: 
       if not m.groups()[0] in excl: 
        filtered.append(m.groups()[1]) 
      else: 
       filtered.append(e) 
     return filtered 

    def run(self): 
     # Remove all TOC entries that should not be on display 
     self.content = self.filter_entries(self.content) 
     return super().run() 

Bây giờ chỉ cần thay đổi toctree chỉ hiện tại của bạn để toctree-filt và bạn tốt để cuộn. Lưu ý rằng Sphinx sẽ đăng lỗi vì nó sẽ tìm các tệp không được bao gồm trong tài liệu. Bạn không chắc chắn cách khắc phục điều đó.