phpmyadmin_ynh/sources/doc/_ext/configext.py

from sphinx.locale import l_, _
from sphinx.domains import Domain, ObjType
from sphinx.roles import XRefRole
from sphinx.domains.std import GenericObject, StandardDomain
from sphinx.directives import ObjectDescription
from sphinx.util.nodes import clean_astext, make_refnode
from sphinx.util import ws_re
from sphinx import addnodes
from sphinx.util.docfields import Field
from docutils import nodes

def get_id_from_cfg(text):
    '''
    Formats anchor ID from config option.
    '''
    if text[:6] == '$cfg[\'':
        text = text[6:]
    if text[-2:] == '\']':
        text = text[:-2]
    text = text.replace('[$i]', '')
    parts = text.split("']['")
    return parts


class ConfigOption(ObjectDescription):
    indextemplate = l_('configuration option; %s')
    parse_node = None

    has_arguments = True

    doc_field_types = [
        Field('default', label=l_('Default value'), has_arg=False,
              names=('default', )),
        Field('type', label=l_('Type'), has_arg=False,
              names=('type',)),
    ]


    def handle_signature(self, sig, signode):
        signode.clear()
        signode += addnodes.desc_name(sig, sig)
        # normalize whitespace like XRefRole does
        name = ws_re.sub('', sig)
        return name

    def add_target_and_index(self, name, sig, signode):
        targetparts =  get_id_from_cfg(name)
        targetname = 'cfg_%s' % '_'.join(targetparts)
        signode['ids'].append(targetname)
        self.state.document.note_explicit_target(signode)
        indextype = 'single'

        # Generic index entries
        indexentry = self.indextemplate % (name,)
        self.indexnode['entries'].append((indextype, indexentry,
                                          targetname, targetname))
        self.indexnode['entries'].append((indextype, name,
                                          targetname, targetname))

        # Server section
        if targetparts[0] == 'Servers' and len(targetparts) > 1:
            indexname = ', '.join(targetparts[1:])
            self.indexnode['entries'].append((indextype, l_('server configuration; %s') % indexname,
                                              targetname, targetname))
            self.indexnode['entries'].append((indextype, indexname,
                                              targetname, targetname))
        else:
            indexname = ', '.join(targetparts)
            self.indexnode['entries'].append((indextype, indexname,
                                              targetname, targetname))

        self.env.domaindata['config']['objects'][self.objtype, name] = \
            self.env.docname, targetname


class ConfigSectionXRefRole(XRefRole):
    """
    Cross-referencing role for configuration sections (adds an index entry).
    """

    def result_nodes(self, document, env, node, is_ref):
        if not is_ref:
            return [node], []
        varname = node['reftarget']
        tgtid = 'index-%s' % env.new_serialno('index')
        indexnode = addnodes.index()
        indexnode['entries'] = [
            ('single', varname, tgtid, varname),
            ('single', _('configuration section; %s') % varname, tgtid, varname)
        ]
        targetnode = nodes.target('', '', ids=[tgtid])
        document.note_explicit_target(targetnode)
        return [indexnode, targetnode, node], []

class ConfigSection(ObjectDescription):
    indextemplate = l_('configuration section; %s')
    parse_node = None

    def handle_signature(self, sig, signode):
        if self.parse_node:
            name = self.parse_node(self.env, sig, signode)
        else:
            signode.clear()
            signode += addnodes.desc_name(sig, sig)
            # normalize whitespace like XRefRole does
            name = ws_re.sub('', sig)
        return name

    def add_target_and_index(self, name, sig, signode):
        targetname = '%s-%s' % (self.objtype, name)
        signode['ids'].append(targetname)
        self.state.document.note_explicit_target(signode)
        if self.indextemplate:
            colon = self.indextemplate.find(':')
            if colon != -1:
                indextype = self.indextemplate[:colon].strip()
                indexentry = self.indextemplate[colon+1:].strip() % (name,)
            else:
                indextype = 'single'
                indexentry = self.indextemplate % (name,)
            self.indexnode['entries'].append((indextype, indexentry,
                                              targetname, targetname))
        self.env.domaindata['config']['objects'][self.objtype, name] = \
            self.env.docname, targetname


class ConfigOptionXRefRole(XRefRole):
    """
    Cross-referencing role for configuration options (adds an index entry).
    """

    def result_nodes(self, document, env, node, is_ref):
        if not is_ref:
            return [node], []
        varname = node['reftarget']
        tgtid = 'index-%s' % env.new_serialno('index')
        indexnode = addnodes.index()
        indexnode['entries'] = [
            ('single', varname, tgtid, varname),
            ('single', _('configuration option; %s') % varname, tgtid, varname)
        ]
        targetnode = nodes.target('', '', ids=[tgtid])
        document.note_explicit_target(targetnode)
        return [indexnode, targetnode, node], []


class ConfigFileDomain(Domain):
    name = 'config'
    label = 'Config'

    object_types = {
            'option':  ObjType(l_('config option'), 'option'),
            'section':  ObjType(l_('config section'), 'section'),
            }
    directives = {
            'option': ConfigOption,
            'section': ConfigSection,
            }
    roles = {
            'option': ConfigOptionXRefRole(),
            'section': ConfigSectionXRefRole(),
            }

    initial_data = {
        'objects': {},      # (type, name) -> docname, labelid
    }

    def clear_doc(self, docname):
        for key, (fn, _) in self.data['objects'].items():
            if fn == docname:
                del self.data['objects'][key]

    def resolve_xref(self, env, fromdocname, builder,
                     typ, target, node, contnode):
        docname, labelid = self.data['objects'].get((typ, target), ('', ''))
        if not docname:
            return None
        else:
            return make_refnode(builder, fromdocname, docname,
                                labelid, contnode)

    def get_objects(self):
        for (type, name), info in self.data['objects'].iteritems():
            yield (name, name, type, info[0], info[1],
                   self.object_types[type].attrs['searchprio'])

def setup(app):
    app.add_domain(ConfigFileDomain)