如何使用 Sphinx 在 reStructuredText 中添加博客樣式標簽

Question

對於用 reStructuredText 編寫並使用 Sphinx 渲染為 HTML 的編程語言文檔項目，我想將我的函數分組到邏輯組中，例如：String（所有字符串函數）、Web（所有與 Web 相關的函數）、List（任何與列表有關的函數）處理）等。現在，由於函數可以是多個組的成員，我想以某種方式添加標簽，就像您添加博客文章一樣。

如果有一個 Sphinx 擴展（或例如使用域的方式）來添加標簽，然后為每個標簽生成一個頁面，引用所有這些功能，所有標簽的概述和底部的交叉引用，那就太棒了每個功能頁面。 這是否可行，如果可行，如何？

例子：

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

您可以利用 sphinx 的索引功能。

休息：

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

Some rest goes here.

配置文件：

html_use_index = True

Answer 2

我已經通過一些自定義預處理和自定義指令解決了這個問題。 我的個人網站是用 Sphinx 制作的，我的博客也是。 博客意味着標簽。

首先是我使用的自定義 Sphinx 指令“標簽”：

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

.. tags:: python, django

Bla bla bla bla

該指令本身將自身轉換為一組../../tags/python.html形式的相對鏈接，這是有效的，因為博客條目總是在yyyy/mm/dd/目錄中。

其次是我從 Sphinx 生成文件調用的一個小的預處理腳本。 這個腳本只是生成一個tags/TAGNAME.txt文件。 Sphinx 將其作為常規 Sphinx 文件處理，因此您只需生成一些有效的重組文本。 例如：

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>

所以核心思想是生成標簽文件並盡可能多地重用常規的 Sphinx 行為。 （我對index.txt 、 yyyy/index.txt 、 yyyy/mm/index.txt等使用相同的方法）。

如果您需要一些示例代碼： https : //github.com/reinout/reinout.vanrees.org/blob/master/rvo/weblog.py