phpmyadmin/doc/_ext/configext.py

   1 from sphinx.locale import l_, _
   2 from sphinx.domains import Domain, ObjType
   3 from sphinx.roles import XRefRole
   4 from sphinx.domains.std import GenericObject, StandardDomain
   5 from sphinx.directives import ObjectDescription
   6 from sphinx.util.nodes import clean_astext, make_refnode
   7 from sphinx.util import ws_re
   8 from sphinx import addnodes
   9 from sphinx.util.docfields import Field
  10 from docutils import nodes
  11
  12 def get_id_from_cfg(text):
  13     '''
  14     Formats anchor ID from config option.
  15     '''
  16     if text[:6] == '$cfg[\'':
  17         text = text[6:]
  18     if text[-2:] == '\']':
  19         text = text[:-2]
  20     text = text.replace('[$i]', '')
  21     parts = text.split("']['")
  22     return parts
  23
  24
  25 class ConfigOption(ObjectDescription):
  26     indextemplate = l_('configuration option; %s')
  27     parse_node = None
  28
  29     has_arguments = True
  30
  31     doc_field_types = [
  32         Field('default', label=l_('Default value'), has_arg=False,
  33               names=('default', )),
  34         Field('type', label=l_('Type'), has_arg=False,
  35               names=('type',)),
  36     ]
  37
  38
  39     def handle_signature(self, sig, signode):
  40         signode.clear()
  41         signode += addnodes.desc_name(sig, sig)
  42         # normalize whitespace like XRefRole does
  43         name = ws_re.sub('', sig)
  44         return name
  45
  46     def add_target_and_index(self, name, sig, signode):
  47         targetparts =  get_id_from_cfg(name)
  48         targetname = 'cfg_%s' % '_'.join(targetparts)
  49         signode['ids'].append(targetname)
  50         self.state.document.note_explicit_target(signode)
  51         indextype = 'single'
  52
  53         # Generic index entries
  54         indexentry = self.indextemplate % (name,)
  55         self.indexnode['entries'].append((indextype, indexentry,
  56                                           targetname, targetname))
  57         self.indexnode['entries'].append((indextype, name,
  58                                           targetname, targetname))
  59
  60         # Server section
  61         if targetparts[0] == 'Servers' and len(targetparts) > 1:
  62             indexname = ', '.join(targetparts[1:])
  63             self.indexnode['entries'].append((indextype, l_('server configuration; %s') % indexname,
  64                                               targetname, targetname))
  65             self.indexnode['entries'].append((indextype, indexname,
  66                                               targetname, targetname))
  67         else:
  68             indexname = ', '.join(targetparts)
  69             self.indexnode['entries'].append((indextype, indexname,
  70                                               targetname, targetname))
  71
  72         self.env.domaindata['config']['objects'][self.objtype, name] = \
  73             self.env.docname, targetname
  74
  75
  76 class ConfigSectionXRefRole(XRefRole):
  77     """
  78     Cross-referencing role for configuration sections (adds an index entry).
  79     """
  80
  81     def result_nodes(self, document, env, node, is_ref):
  82         if not is_ref:
  83             return [node], []
  84         varname = node['reftarget']
  85         tgtid = 'index-%s' % env.new_serialno('index')
  86         indexnode = addnodes.index()
  87         indexnode['entries'] = [
  88             ('single', varname, tgtid, varname),
  89             ('single', _('configuration section; %s') % varname, tgtid, varname)
  90         ]
  91         targetnode = nodes.target('', '', ids=[tgtid])
  92         document.note_explicit_target(targetnode)
  93         return [indexnode, targetnode, node], []
  94
  95 class ConfigSection(ObjectDescription):
  96     indextemplate = l_('configuration section; %s')
  97     parse_node = None
  98
  99     def handle_signature(self, sig, signode):
 100         if self.parse_node:
 101             name = self.parse_node(self.env, sig, signode)
 102         else:
 103             signode.clear()
 104             signode += addnodes.desc_name(sig, sig)
 105             # normalize whitespace like XRefRole does
 106             name = ws_re.sub('', sig)
 107         return name
 108
 109     def add_target_and_index(self, name, sig, signode):
 110         targetname = '%s-%s' % (self.objtype, name)
 111         signode['ids'].append(targetname)
 112         self.state.document.note_explicit_target(signode)
 113         if self.indextemplate:
 114             colon = self.indextemplate.find(':')
 115             if colon != -1:
 116                 indextype = self.indextemplate[:colon].strip()
 117                 indexentry = self.indextemplate[colon+1:].strip() % (name,)
 118             else:
 119                 indextype = 'single'
 120                 indexentry = self.indextemplate % (name,)
 121             self.indexnode['entries'].append((indextype, indexentry,
 122                                               targetname, targetname))
 123         self.env.domaindata['config']['objects'][self.objtype, name] = \
 124             self.env.docname, targetname
 125
 126
 127 class ConfigOptionXRefRole(XRefRole):
 128     """
 129     Cross-referencing role for configuration options (adds an index entry).
 130     """
 131
 132     def result_nodes(self, document, env, node, is_ref):
 133         if not is_ref:
 134             return [node], []
 135         varname = node['reftarget']
 136         tgtid = 'index-%s' % env.new_serialno('index')
 137         indexnode = addnodes.index()
 138         indexnode['entries'] = [
 139             ('single', varname, tgtid, varname),
 140             ('single', _('configuration option; %s') % varname, tgtid, varname)
 141         ]
 142         targetnode = nodes.target('', '', ids=[tgtid])
 143         document.note_explicit_target(targetnode)
 144         return [indexnode, targetnode, node], []
 145
 146
 147 class ConfigFileDomain(Domain):
 148     name = 'config'
 149     label = 'Config'
 150
 151     object_types = {
 152             'option':  ObjType(l_('config option'), 'option'),
 153             'section':  ObjType(l_('config section'), 'section'),
 154             }
 155     directives = {
 156             'option': ConfigOption,
 157             'section': ConfigSection,
 158             }
 159     roles = {
 160             'option': ConfigOptionXRefRole(),
 161             'section': ConfigSectionXRefRole(),
 162             }
 163
 164     initial_data = {
 165         'objects': {},      # (type, name) -> docname, labelid
 166     }
 167
 168     def clear_doc(self, docname):
 169         for key, (fn, _) in self.data['objects'].items():
 170             if fn == docname:
 171                 del self.data['objects'][key]
 172
 173     def resolve_xref(self, env, fromdocname, builder,
 174                      typ, target, node, contnode):
 175         docname, labelid = self.data['objects'].get((typ, target), ('', ''))
 176         if not docname:
 177             return None
 178         else:
 179             return make_refnode(builder, fromdocname, docname,
 180                                 labelid, contnode)
 181
 182     def get_objects(self):
 183         for (type, name), info in self.data['objects'].iteritems():
 184             yield (name, name, type, info[0], info[1],
 185                    self.object_types[type].attrs['searchprio'])
 186
 187 def setup(app):
 188     app.add_domain(ConfigFileDomain)
 189