Python 如何使用Sphinx在reStructuredText中添加博客样式标记

对于用StructuredText编写并用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

子串
=========
**子字符串（****\****文本，***编号***开始，***编号***结束*）**
描述
-----------
返回字符串“%text”的子字符串
在整数位置“开始”和位置“结束”之间。
字符串中的第一个字符编号为0。
“substring”返回的最后一个字符是位置“end”之前的字符。
也可以省略“end”，这意味着
返回的字符串将在``text``的最后一个位置结束。
例子
-------
执行以下代码：
::
日志（子字符串（“欢迎访问我们的站点！”，0,7））；
日志（子字符串（“欢迎访问我们的网站！”，0））；
将打印：
::
欢迎
欢迎来到我们的网站！
标签
----
一串

我通过一些自定义预处理和自定义指令解决了这个问题。我的个人网站是用斯芬克斯制作的，我的博客也是如此。而博客意味着标签

首先是自定义Sphinx指令“标记”，我这样使用：

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

.. tags:: python, django

Bla bla bla bla

该指令本身将自身转换为一组相对链接，其形式为

。/../tags/python.html

，这是因为博客条目始终位于

yyyy/mm/dd/

目录中

第二个是我从Sphinx makefile调用的小预处理脚本。此脚本只生成一个

标记/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>

python
######
.. 目录树：：
：maxdepth:1
2013-08-23 github pull请求获得好评
2013-08-21如何用Python编程说“`[：]`”
2013-08-15方便的回溯，而不是无信息的断层

因此，核心思想是生成标记文件并尽可能多地重复使用Sphinx的常规行为。（我对

index.txt

，

yyyy/index.txt

，

yyy/mm/index.txt

等使用相同的方法）

---

如果您需要一些示例代码：

您可以使用sphinx的索引功能

其余：

。。索引：：BNF、语法、语法、符号
这里有一些休息。

conf.py：

html_use_index = True