如何使用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.

conf.py：

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 makefile 调用。该脚本只是生成一个

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

Answer 3

您可以使用两个扩展：sphinx-tags或ablog。第一个仅包含与标签相关的指令。第二个是 sphinx 文档的整个博客转换。