如何使用Sphinx在reStructuredText中添加博客样式标签 [英] How to add blog style tags in reStructuredText with Sphinx
问题描述
如果有一个Sphinx扩展名（例如使用域名的方式）添加标签，然后生成一个引用所有这些功能的标签页，所有标签的概述和每个功能页面底部的交叉引用。这是可行的，如果是的话，怎么样？
示例：
---------
substring
---------
** substring（** \ *< string，number> * **文字，** *号* **开始，** *号* **结束*）**
描述
-----------
返回整数位置``start``和位置``end``之间的字符串``text``的子串。字符串中的第一个字符编号为0.substring返回的最后一个字符是位置end之前的字符。可选择``end``可以省略，这意味着返回的字符串将结束于``text``的最后一个位置。
示例
-------
-
执行以下代码：
::
log（substring（Welcome to our site！，0，7））;
log（substring（Welcome to our site！，0））;
将打印：
::
欢迎
欢迎来到我们的网站！
标签
----
字符串
我已经通过一些自定义预处理和自定义指令解决了这个问题。我的个人网站是用Sphinx制作的，和我的博客一样。而且一个网络日志表示标签。
首先使用这样的自定义Sphinx指令标签：
我的博客条目标题
==================
..标签:: python，django
Bla bla bla bla
该指令本身将其自身转换成一组形式为 ../../ tags / python.html 的相对链接，因为博客条目始终位于 yyyy / mm / dd / 目录。
第二个我称之为小型预处理脚本从狮身人面像makefile。该脚本只生成一个标签/ TAGNAME.txt 文件。 Sphinx将其处理为常规的Sphinx文件，因此您只需生成一些有效的重组文本。例如：
python
######
.. toctree： ：
：maxdepth：1
2013-08-23赞美github拉请求< ../ 2013/08/23 / praise-for-pull-requests.txt>
2013-08-21如何在Python中编程``[：]``\\ 2013/08/21 / programmatical-all-range.txt>
2013-08-15方便的追溯而不是不了解的segfaults< ../ 2013/08/15 / handy-tracebacks-with-faulthandler.txt>
所以核心思想是生成标签文件，并重新使用尽可能多的常规Sphinx行为。 （我对 index.txt ， yyyy / index.txt ， yyyy使用相同的方法/ / code>等等）。
如果您需要一些示例代码： https://github.com/reinout/reinout.vanrees.org/blob/master/rvo/ weblog.py
For a programming language documentation project written in reStructuredText and rendered to HTML with Sphinx, I want to group my functions into logical groups like: String (all string functions), Web (all web-related functions), List (anything to do with list handling), etc.. Now, since functions can be members of several groups I want to add tags in some way, just like you would to blog posts.
It would be really neat if there were a Sphinx extension (or way of using Domains for example) to add the tags and then generate a page per tag referencing all those functions, an overview of all tags and a cross-reference at the bottom of each function page. Is this feasible and if so, how?
Example:
---------
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
I've solved this with some custom preprocessing and a custom directive. My personal website is made with Sphinx, as is my weblog. And a weblog means tags.
First the custom Sphinx directive "tags" that I use like this:
My blog entry header
====================
.. tags:: python, django
Bla bla bla bla
The directive itself translates itself to a bunch of relative links of the form ../../tags/python.html, which works because the blog entries are always in yyyy/mm/dd/ directories.
Second a small preprocessing script that I call from the Sphinx makefile. This script simply generates a tags/TAGNAME.txt file. Sphinx processes it as a regular Sphinx file, so you only have to generate some valid restructured text. For instance:
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>
So the core idea is to generate the tag files and re-use as much regular Sphinx behavior as possible. (I use the same approach for index.txt, yyyy/index.txt, yyyy/mm/index.txt and so on).
In case you need some example code: https://github.com/reinout/reinout.vanrees.org/blob/master/rvo/weblog.py
这篇关于如何使用Sphinx在reStructuredText中添加博客样式标签的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
