granicus.if.org Git - esp-idf/blob - tools/kconfig_new/gen_kconfig_doc.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3 #
   4 # gen_kconfig_doc - confgen.py support for generating ReST markup documentation
   5 #
   6 # For each option in the loaded Kconfig (e.g. 'FOO'), CONFIG_FOO link target is
   7 # generated, allowing options to be referenced in other documents
   8 # (using :ref:`CONFIG_FOO`)
   9 #
  10 # Copyright 2017-2018 Espressif Systems (Shanghai) PTE LTD
  11 #
  12 # Licensed under the Apache License, Version 2.0 (the "License");
  13 # you may not use this file except in compliance with the License.
  14 # You may obtain a copy of the License at
  15 #
  16 #     http:#www.apache.org/licenses/LICENSE-2.0
  17 #
  18 # Unless required by applicable law or agreed to in writing, software
  19 # distributed under the License is distributed on an "AS IS" BASIS,
  20 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  21 # See the License for the specific language governing permissions and
  22 # limitations under the License.
  23 import os
  24 import kconfiglib
  25
  26 # Indentation to be used in the generated file
  27 INDENT = '    '
  28
  29 # Characters used when underlining section heading
  30 HEADING_SYMBOLS = '#*=-^"+'
  31
  32 # Keep the heading level in sync with api-reference/kconfig.rst
  33 INITIAL_HEADING_LEVEL = 3
  34 MAX_HEADING_LEVEL = len(HEADING_SYMBOLS)-1
  35
  36 def write_docs(config, filename):
  37     """ Note: writing .rst documentation ignores the current value
  38     of any items. ie the --config option can be ignored.
  39     (However at time of writing it still needs to be set to something...) """
  40     with open(filename, "w") as f:
  41         config.walk_menu(lambda node: write_menu_item(f, node))
  42
  43
  44 def get_breadcrumbs(node):
  45     # this is a bit wasteful as it recalculates each time, but still...
  46     result = []
  47     node = node.parent
  48     while node.parent:
  49         if node.prompt:
  50             result = [ node.prompt[0] ] + result
  51         node = node.parent
  52     return " > ".join(result)
  53
  54 def get_heading_level(node):
  55     # bit wasteful also
  56     result = INITIAL_HEADING_LEVEL
  57     node = node.parent
  58     while node.parent:
  59         result += 1
  60         if result == MAX_HEADING_LEVEL:
  61             return MAX_HEADING_LEVEL
  62         node = node.parent
  63     return result
  64
  65 def format_rest_text(text, indent):
  66     # Format an indented text block for use with ReST
  67     text = indent + text.replace('\n', '\n' + indent)
  68     # Escape some characters which are inline formatting in ReST
  69     text = text.replace("*", "\\*")
  70     text = text.replace("_", "\\_")
  71     text += '\n'
  72     return text
  73
  74 def write_menu_item(f, node):
  75     if not node.prompt:
  76         return  # Don't do anything for invisible menu items
  77
  78     if isinstance(node.parent.item, kconfiglib.Choice):
  79         return  # Skip choice nodes, they are handled as part of the parent (see below)
  80
  81     try:
  82         name = node.item.name
  83     except AttributeError:
  84         name = None
  85
  86     try:
  87         is_menu = node.item == kconfiglib.MENU or node.is_menuconfig
  88     except AttributeError:
  89         is_menu = False  # not all MenuNodes have is_menuconfig for some reason
  90
  91     ## Heading
  92     if name:
  93         title = name
  94         # add link target so we can use :ref:`CONFIG_FOO`
  95         f.write('.. _CONFIG_%s:\n\n' % name)
  96     else:
  97         title = node.prompt[0]
  98
  99     # if no symbol name, use the prompt as the heading
 100     if True or is_menu:
 101         f.write('%s\n' % title)
 102         f.write(HEADING_SYMBOLS[get_heading_level(node)] * len(title))
 103         f.write('\n\n')
 104     else:
 105         f.write('**%s**\n\n\n' % title)
 106
 107     if name:
 108         f.write('%s%s\n\n' % (INDENT, node.prompt[0]))
 109         f.write('%s:emphasis:`Found in: %s`\n\n' % (INDENT, get_breadcrumbs(node)))
 110
 111     try:
 112         if node.help:
 113             # Help text normally contains newlines, but spaces at the beginning of
 114             # each line are stripped by kconfiglib. We need to re-indent the text
 115             # to produce valid ReST.
 116             f.write(format_rest_text(node.help, INDENT))
 117     except AttributeError:
 118         pass  # No help
 119
 120     if isinstance(node.item, kconfiglib.Choice):
 121         f.write('%sAvailable options:\n' % INDENT)
 122         choice_node = node.list
 123         while choice_node:
 124             # Format available options as a list
 125             f.write('%s- %-20s (%s)\n' % (INDENT * 2, choice_node.prompt[0], choice_node.item.name))
 126             if choice_node.help:
 127                 HELP_INDENT = INDENT * 2
 128                 fmt_help = format_rest_text(choice_node.help, '  ' + HELP_INDENT)
 129                 f.write('%s  \n%s\n' % (HELP_INDENT, fmt_help))
 130             choice_node = choice_node.next
 131
 132         f.write('\n\n')
 133
 134
 135 if __name__ == '__main__':
 136     print("Run this via 'confgen.py --output doc FILENAME'")
 137