docs (Sphinx): handle :config:option: for different types of data

Examples:

Daemon:
    :config:option:`sd`

Resource Type:
    :config:option:`dir/job`

Resource Name:
    :config:option:`dir/job = backup-client1`

(Reference to a) Resource Directive:
    :config:option:`dir/job/TlsAlwaysIncrementalMaxFullAcl`

Resource Directive With Value:
    :config:option:`dir/job/TlsAlwaysIncrementalMaxFullAcl = False`

docs/manuals/en/new_main_reference/source/DocumentationStyleGuide/BareosSpecificFormatting/BareosConfiguration.rst

@@ -68,11 +68,6 @@ This will get displayed as
 
 :config:option:`dir/job`
 
-TODO
-~~~~
-
-  * needs implmentation
-
 
 Resource Name
 -------------
@@ -86,10 +81,6 @@ This will get displayed as
 
 :config:option:`dir/job = backup-client1`
 
-TODO
-~~~~
-
-    * needs implmentation
 
 Resource Directive
 ------------------
@@ -168,7 +159,3 @@ This will get displayed as
 
 :config:option:`dir/job/AlwaysIncrementalJobRetention = 900`
 
-TODO
-^^^^
-
-  * needs implmentation

docs/manuals/en/new_main_reference/source/_extensions/bareos-ext.py

@@ -55,37 +55,59 @@ def get_config_directive(text):
     '''
     This function generates from the signature
     the different required formats of a configuration directive.
-    The signature (text) must be given as
+    The signature (text) must be given (depending on the type) as:
 
-    <dir|sd|fd|console>/<resourcetype_lower_case>/<DirectiveInCamelCase>
+    <dir|sd|fd|console>/<resourcetype_lower_case>/<DirectiveInCamelCase> = <value>
 
-    For example:
+    Examples for the different types:
+
+    Daemon:
+    dir
+
+    Resource Type:
+    dir/job
+
+    Resource Name:
+    dir/job = backup-client1
+
+    (Reference to a) Resource Directive:
     dir/job/TlsAlwaysIncrementalMaxFullAcl
+
+    Resource Directive With Value:
+    dir/job/TlsAlwaysIncrementalMaxFullAcl = False
     '''
+
     logger = logging.getLogger(__name__)
-    displaynametemplate = u'{Directive} ({Dmn}->{Resource})'
-    indextemplate  = u'Configuration Directive; ' + displaynametemplate
+    displayTemplateDaemon = u'{Daemon}'
+    displayTemplateResourceType = u'{Resource} ({Dmn})'
+    displayTemplateResourceName = u'{Resource} ({Dmn}) = {value}'
+    displayTemplateResourceDirective = u'{Directive} ({Dmn}->{Resource})'
+    displayTemplateResourceDirectiveWithValue = u'{Directive} ({Dmn}->{Resource}) = {value}'
+    indextemplate  = u'Configuration Directive; ' + displayTemplateResourceDirective
+    internaltargettemplate = u'{dmn}/{resource}/{CamelCaseDirective}'
 
     # Latex: directiveDirJobCancel%20Lower%20Level%20Duplicates
     # The follow targettemplate will create identical anchors as Latex,
     # but as the base URL is likly it be different, it does not help (and still looks ugly).
     # targettemplate = u'directive{dmn}{resource}{directive}'
     targettemplate = u'config-{Dmn}_{Resource}_{CamelCaseDirective}'
 
-    input_daemon = None
-    input_resource = None
+    result = {
+        'signature': text,
+    }
+
     try:
-        input_daemon, input_resource, input_directive = text.split('/', 2)
+        key, value = text.split('=', 1)
+        result['value'] = value.strip()
     except ValueError:
         # fall back
-        input_directive = text
+        key = text
 
-    result = {
-        'signature': text,
-    }
+    inputComponent = key.strip().split('/', 2)
+    components = len(inputComponent)
 
-    if input_daemon:
-        daemon = input_daemon.lower()
+    if components >= 1:
+        daemon = inputComponent[0].lower()
         if daemon == 'director' or daemon == 'dir':
             result['Daemon'] = 'Director'
             result['dmn'] = 'dir'
@@ -103,33 +125,35 @@ def get_config_directive(text):
             result['dmn'] = 'console'
             result['Dmn'] = 'Console'
         else:
+            # TODO: raise
             result['Daemon'] = 'UNKNOWN'
             result['dmn'] = 'UNKNOWN'
             result['Dmn'] = 'UNKNOWN'
+        result['displayname'] = displayTemplateDaemon.format(**result)
 
-    else:
-        result['Daemon'] = None
-        result['Dmn'] = None
-        result['dmn'] = None
-
-    if input_resource:
-        result['resource'] = input_resource.replace(' ', '').lower()
-        result['Resource'] = input_resource.replace(' ', '').capitalize()
-    else:
-        result['resource'] = None
-        result['Resource'] = None
-
-
-    # input_directive should be without spaces.
-    # However, we make sure, by removing all spaces.
-    result['CamelCaseDirective'] = input_directive.replace(' ', '')
-    result['Directive'] = convertCamelCase2Spaces(result['CamelCaseDirective'])
+    if components >= 2:
+        result['resource'] = inputComponent[1].replace(' ', '').lower()
+        result['Resource'] = inputComponent[1].replace(' ', '').capitalize()
+        if 'value' in result:
+            result['displayname'] = displayTemplateResourceName.format(**result)
+        else:
+            result['displayname'] = displayTemplateResourceType.format(**result)
+
+    if components >= 3:
+        # input_directive should be without spaces.
+        # However, we make sure, by removing all spaces.
+        result['CamelCaseDirective'] = inputComponent[2].replace(' ', '')
+        result['Directive'] = convertCamelCase2Spaces(result['CamelCaseDirective'])
+        if 'value' in result:
+            result['displayname'] = displayTemplateResourceDirectiveWithValue.format(**result)
+        else:
+            result['displayname'] = displayTemplateResourceDirective.format(**result)
 
-    result['displayname'] = displaynametemplate.format(**result)
-    result['indexentry'] = indextemplate.format(**result)
-    result['target'] = targettemplate.format(**result)
+        result['indexentry'] = indextemplate.format(**result)
+        result['target'] = targettemplate.format(**result)
+        result['internaltarget'] = internaltargettemplate.format(**result)
 
-    logger.debug('[bareos] ' + pformat(result))
+    #logger.debug('[bareos] ' + pformat(result))
 
     return result
 
@@ -200,10 +224,11 @@ def add_target_and_index(self, name, sig, signode):
         signode['ids'].append(targetname)
         self.state.document.note_explicit_target(signode)
 
-        indextype = 'single'
-        # Generic index entries
-        self.indexnode['entries'].append((indextype, directive['indexentry'],
-                                          targetname, targetname, None))
+        if 'indexentry' in directive:
+            indextype = 'single'
+            # Generic index entries
+            self.indexnode['entries'].append((indextype, directive['indexentry'],
+                                            targetname, targetname, None))
 
         self.env.domaindata['config']['objects'][self.objtype, sig] = \
             self.env.docname, targetname
@@ -216,15 +241,18 @@ class ConfigOptionXRefRole(XRefRole):
 
     def result_nodes(self, document, env, node, is_ref):
         logger = logging.getLogger(__name__)
-        logger.debug('[bareos] is_ref: {}, node[reftarget]: {}, {}'.format(str(is_ref), node['reftarget'], type(node['reftarget'])))
+        #logger.debug('[bareos] is_ref: {}, node[reftarget]: {}, {}'.format(str(is_ref), node['reftarget'], type(node['reftarget'])))
+        #logger.debug('[bareos] ' + pformat(result))
 
         if not is_ref:
             return [node], []
 
         varname = node['reftarget']
-
         directive = get_config_directive(varname)
 
+        if not 'indexentry' in directive:
+            return [node], []
+
         tgtid = 'index-%s' % env.new_serialno('index')
 
         indexnode = addnodes.index()
@@ -239,12 +267,20 @@ def result_nodes(self, document, env, node, is_ref):
 
 
     def process_link(self, env, refnode, has_explicit_title, title, target):
+
+        logger = logging.getLogger(__name__)
+
         if has_explicit_title:
             return title, target
 
         directive = get_config_directive(title)
-        return directive['displayname'], target
+        #logger.debug('process_link({}, {})'.format(title, target))
+        #logger.debug('process_link: ' + pformat(directive))
 
+        if 'internaltarget' in directive:
+            return directive['displayname'], directive['internaltarget']
+        else:
+            return directive['displayname'], target