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