8

reStructuredText で記述され、Sphinx を使用して HTML にレンダリングされたプログラミング言語ドキュメント プロジェクトの場合、関数を次のような論理グループにグループ化したいと考えています。関数は複数のグループのメンバーになる可能性があるため、ブログ投稿と同じように、何らかの方法でタグを追加したいと考えています。

タグを追加し、タグごとにこれらすべての機能を参照するページ、すべてのタグの概要、およびページの下部にある相互参照を生成するための 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
4

2 に答える 2

12

sphinx のインデックス機能を利用できます。

休み：

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

Some rest goes here.

conf.py:

html_use_index = True
于 2013-11-07T13:24:07.950 に答える
8

カスタム前処理とカスタム ディレクティブでこれを解決しました。私の個人的なウェブサイトは、ブログと同様に Sphinx で作成されています。そしてウェブログはタグを意味します。

最初に、私が次のように使用するカスタム Sphinx ディレクティブ「タグ」:

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

.. tags:: python, django

Bla bla bla bla

ディレクティブ自体は、形式の相対リンクの束に変換されます。../../tags/python.htmlこれは、ブログ エントリが常にyyyy/mm/dd/ディレクトリにあるため機能します。

2 つ目は、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

于 2013-09-04T08:14:09.097 に答える