Adding custom directives and roles for Sphinx syntax it also provide index information / Sphinxの独自directive, roleを定義してアウトプットを整形したりindex化したり。

conf.py

# http://sphinx-users.jp/doc11/ext/appapi.html#sphinx.application.Sphinx.add_object_type

# -- add config field --

from sphinx import addnodes
from sphinx.util.docfields import Field, GroupedField
import re


def iniref_parse_format(env, sig, signode):
    # parse directive argument for indexing
    m = re.match(r'(\[[^]]*\])([^=]*)=(.*)', sig)
    if m:
        sec, key, value = [x.strip() for x in m.groups()]
    else:
        sec = 'DEFAULT'
        key = [x.strip() for x in sig.split('=',1)][0]
    signode += addnodes.desc_name(sig, sig)
    return "%s; %s" % (sec, key)  #return pair index

def pydefine_parse_format(env, sig, signode):
    # parse directive argument for indexing
    fn, key = [x.strip() for x in sig.split(':',1)]
    signode += addnodes.desc_name(sig, sig)
    return "%s; %s" % (fn, key)  #return pair index

def setup(app):
    # define option field
    freq = Field('required', label='Required',
                 names=['req', 'required'], has_arg=False)
    fdef = GroupedField('default', label='Default',
                        names=['default'], can_collapse=True)
    fsample = Field('sample', label='Sample', names=['sample'], has_arg=False)

    # define new directive and role: iniref
    app.add_object_type('iniref', 'iniref',
                        objname='configration value',
                        indextemplate='triple: %s; (ini)',
                        parse_node=iniref_parse_format,
                        doc_field_types=[freq, fdef, fsample])
                        
    
    # define new directive and role: pydefine
    app.add_object_type('pydefine', 'pydefine',
                        objname='python define value',
                        indextemplate='triple: %s; (define)',
                        parse_node=pydefine_parse_format,
                        doc_field_types=[freq, fdef, fsample])

gunicorn-conf.txt

.. rst format

gunicorn.conf のサンプル
---------------------------

.. code-block:: python

   import os
   BASEDIR = os.path.dirname(os.path.abspath(__file__))

   pidfile = os.path.join(BASEDIR, 'logs', proc_name+'.pid')
   accesslog = os.path.join(BASEDIR, 'logs', proc_name+'-access.log')
   errorlog = os.path.join(BASEDIR, 'logs', proc_name+'-error.log')

   debug = True
   workers = 1
   preload_app = False
   max_requests = 1
   daemon = True
   proc_name = 'devsite'
   ...


gunicorn.conf リファレンス
-------------------------------------

.. pydefine::
   gunicorn.conf: pidfile
   gunicorn.conf: accesslog
   gunicorn.conf: errorlog

   pid,log等の保存先を設定します。

   :required: False
   :default: None
   :sample: /path/to/logs/appname-access.log

.. pydefine:: gunicorn.conf: daemon

   daemonとして起動する場合はTrueに設定します。

   :required: False
   :default: False
   :sample: True

repoze-who-plugin.txt

.. rst format

who.ini sample
------------------

.. code-block:: ini

   [plugin:mongoauth]
   use = plugins.mongo:make_authenticator_plugin
   conn_uri = mongodb://localhost:27017/test/developers
   ...

[plugin:mongoauth]
-------------------

.. iniref:: [plugin:mongoauth]use = plugins.mongo:make_authenticator_plugin

   repoze.whoに認証プラグインモジュールを追加します。

   :required: True


.. iniref:: [plugin:mongoauth]conn_uri = mongodb://HOSTNAME[:PORT]/DATABASE/COLLECTION

   mongoauthプラグインが参照する認証情報が格納されたMongoDBのコレクションを指定>します。

   :required: True
   :sample: mongodb://localhost:27017/test/developers