Come aggiungere tag stile blog in reStructuredText with Sphinx

Question

Per un progetto di documentazione in linguaggio di programmazione scritto in reStructuredText e reso in HTML con Sphinx, desidero raggruppare le mie funzioni in gruppi logici come: String (tutte le funzioni stringa), Web (tutto funzioni relative al Web), Elenco (qualsiasi cosa abbia a che fare con la gestione delle liste), ecc. Ora, poiché le funzioni possono essere membri di diversi gruppi, voglio aggiungere tag in qualche modo, proprio come faresti per i post dei blog.

Sarebbe davvero bello se ci fosse un'estensione Sfinge (o un modo di usare domini per esempio) per aggiungere i tag e quindi generare una pagina per tag riferendosi a tutte quelle funzioni, una panoramica di tutti i tag e un riferimento incrociato nella parte inferiore di ogni pagina di funzione. È fattibile e se sì, come?

Esempio:

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

Ho risolto questo con un po 'di pre-elaborazione personalizzato e una direttiva personalizzato. Il mio sito web personale è realizzato con Sphinx, come il mio blog. E un weblog significa tag.

Prima i personalizzati Sphinx direttiva "tag" che uso in questo modo:

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

.. tags:: python, django 

Bla bla bla bla 

La direttiva stessa si traduce in un mazzo di collegamenti relativi della forma ../../tags/python.html, che funziona perché le voci del blog sono sempre nelle directory yyyy/mm/dd/.

Secondo uno piccolo script di pre-elaborazione che chiamo dal makefile Sfinge. Questo script genera semplicemente un file tags/TAGNAME.txt. Sfinge lo elabora come un normale file Sphinx, quindi devi solo generare un testo ristrutturato valido. Ad esempio:

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> 

Quindi l'idea di base è generare i file di tag e riutilizzare il più possibile il comportamento regolare di Sfinge. (Uso lo stesso approccio per index.txt, yyyy/index.txt, yyyy/mm/index.txt e così via).

Nel caso in cui avete bisogno di qualche codice di esempio: https://github.com/reinout/reinout.vanrees.org/blob/master/rvo/weblog.py

Answer 2

È possibile fare uso di funzione di indicizzazione di sfinge.

turismo:

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

Some rest goes here. 

conf.py:

html_use_index = True