Cách thêm thẻ kiểu blog trong reStructuredText bằng Sphinx

Question

Đối với dự án tài liệu ngôn ngữ lập trình được viết bằng reStructuredText và được hiển thị thành HTML bằng Sphinx, tôi muốn nhóm các chức năng của mình thành các nhóm logic như: String (tất cả các hàm chuỗi), Web (tất cả các chức năng liên quan đến web), Danh sách (mọi thứ cần làm với xử lý danh sách), v.v. Bây giờ, vì các hàm có thể là thành viên của một số nhóm, tôi muốn thêm các thẻ theo cách nào đó, giống như các bài đăng trên blog.

Nó sẽ thực sự gọn gàng nếu có phần mở rộng Sphinx (hoặc cách sử dụng tên miền) để thêm thẻ và sau đó tạo một trang cho mỗi thẻ tham chiếu tất cả các chức năng đó, tổng quan về tất cả các thẻ và tham chiếu chéo ở cuối mỗi trang chức năng. Điều này có khả thi không và nếu có thì làm thế nào?

Ví dụ:

--------- 
substring 
--------- 

**substring (**\ *<string,number>* **text,** *number* **start,** *number* **end*)** 

Description 
----------- 

Returns the substring of string ``text`` between integer positions ``start`` and position ``end``. The first character in the string is numbered 0. The last character returned by ``substring`` is the character before position ``end``. Optionally ``end`` can be left out, which means the returned string will end at the last position of ``text``. 

Example 
------- 

- 

    Executing the following code: 

    :: 

     log(substring("Welcome to our site!", 0, 7)); 
     log(substring("Welcome to our site!", 0)); 

    will print: 

    :: 

     Welcome 
     Welcome to our site! 

Tags 
---- 

String 

Answer 1

Tôi đã giải quyết này với một số tiền xử lý tùy chỉnh và một chỉ thị tùy chỉnh. Trang web cá nhân của tôi được tạo bằng Sphinx, cũng như nhật ký web của tôi. Và một weblog có nghĩa là các thẻ.

Đầu tiên tùy chỉnh Sphinx chỉ "thẻ" mà tôi sử dụng như thế này:

My blog entry header 
==================== 

.. tags:: python, django 

Bla bla bla bla 

Chỉ thị bản thân dịch tự nó lên một loạt các liên kết tương đối có dạng ../../tags/python.html, mà làm việc vì các mục blog là luôn trong các thư mục yyyy/mm/dd/.

Thứ hai là tập lệnh tiền xử lý nhỏ mà tôi gọi từ tệp giả mạo Nhân sư. Tập lệnh này chỉ tạo một tệp tags/TAGNAME.txt. Nhân sư xử lý nó như một tệp Sphinx thông thường, vì vậy bạn chỉ phải tạo một số văn bản được cấu trúc lại hợp lệ. Ví dụ:

python 
###### 

.. toctree:: 
    :maxdepth: 1 

    2013-08-23 Praise for github pull requests <../2013/08/23/praise-for-pull-requests.txt> 
    2013-08-21 How to say ``[:]`` programmatically in Python <../2013/08/21/programmatical-all-range.txt> 
    2013-08-15 Handy tracebacks instead of uninformative segfaults <../2013/08/15/handy-tracebacks-with-faulthandler.txt> 

Vì vậy, ý tưởng cốt lõi là tạo tệp thẻ và sử dụng lại nhiều hành vi Sphinx thông thường nhất có thể. (Tôi sử dụng cùng một cách tiếp cận cho index.txt, yyyy/index.txt, yyyy/mm/index.txt và cứ tiếp tục).

Trong trường hợp bạn cần một số mã ví dụ: https://github.com/reinout/reinout.vanrees.org/blob/master/rvo/weblog.py

Answer 2

Bạn có thể tận dụng tính năng lập chỉ mục của Sphinx.

còn lại:

.. index:: BNF, grammar, syntax, notation 

Some rest goes here. 

conf.py:

html_use_index = True