Wie man Blog-Stil-Tags in reStructuredText mit Sphinx hinzufügt

Question

Für eine Programmiersprache Dokumentationsprojekt in reStructuredText geschrieben und in HTML mit Sphinx gerendert, möchte ich meine Funktionen in logische Gruppen wie: String (alle String-Funktionen), Web (alle Web-bezogene Funktionen), Liste (alles was mit der Listenbehandlung zu tun hat), etc .. Nun, da Funktionen Mitglieder mehrerer Gruppen sein können, möchte ich Tags in irgendeiner Weise hinzufügen, genau wie Sie es bei Blogposts tun würden.

Es wäre wirklich nett, wenn es eine Sphinx-Erweiterung (oder eine Art der Verwendung von Domains zum Beispiel) gäbe, um die Tags hinzuzufügen und dann eine Seite pro Tag zu generieren, die auf all diese Funktionen verweist, eine Übersicht aller Tags und einen Querverweis am unteren Rand jeder Funktionsseite. Ist das machbar und wenn ja, wie?

Beispiel:

--------- 
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

Ich habe dies mit einigen benutzerdefinierten Vorverarbeitung gelöst und eine benutzerdefinierte Richtlinie. Meine persönliche Website wird mit Sphinx erstellt, genauso wie mein Weblog. Und ein Weblog bedeutet Tags.

Zuerst werden die benutzerdefinierte Sphinx Richtlinie „Tags“, die ich wie folgt verwenden:

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

.. tags:: python, django 

Bla bla bla bla 

Die Richtlinie selbst übersetzt sich in eine Reihe von relativen Links der Form ../../tags/python.html, die funktioniert, weil die Blog-Einträge immer in yyyy/mm/dd/ Verzeichnisse.

Sekunde ein kleine Vorverarbeitung Skript, die ich aus dem Sphinx-Makefile aufrufen. Dieses Skript generiert einfach eine tags/TAGNAME.txt Datei. Sphinx verarbeitet es als reguläre Sphinx-Datei, sodass Sie nur einen gültigen restrukturierten Text generieren müssen. Zum Beispiel:

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> 

Die Kernidee besteht also darin, die Tag-Dateien zu generieren und so viel reguläres Sphinx-Verhalten wie möglich wiederzuverwenden. (Ich verwende den gleichen Ansatz für index.txt, yyyy/index.txt, yyyy/mm/index.txt und so weiter).

Im Fall müssen Sie einige Beispiel-Code: https://github.com/reinout/reinout.vanrees.org/blob/master/rvo/weblog.py

Answer 2

Sie Verwendung von Indexierungsfunktion der Sphinx machen.

ReST:

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

Some rest goes here. 

conf.py:

html_use_index = True