granicus.if.org Git - esp-idf/blob - docs/gen-kconfig-doc.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3 #
   4 # gen-kconfig-doc.py — generate Sphinx .rst file from Kconfig files
   5 #
   6 # This script iterates over Kconfig and Kconfig.projbuild files in
   7 # ESP-IDF component directories, and outputs documentation for these options
   8 # as ReST markup.
   9 # For each option in Kconfig file (e.g. 'FOO'), CONFIG_FOO link target is
  10 # generated, allowing options to be referenced in other documents
  11 # (using :envvar:`CONFIG_FOO`)
  12 #
  13 # This script uses kconfiglib library to do all the work of parsing Kconfig
  14 # files: https://github.com/ulfalizer/Kconfiglib
  15 #
  16 # Copyright 2017 Espressif Systems (Shanghai) PTE LTD
  17 #
  18 # Licensed under the Apache License, Version 2.0 (the "License");
  19 # you may not use this file except in compliance with the License.
  20 # You may obtain a copy of the License at
  21 #
  22 #     http:#www.apache.org/licenses/LICENSE-2.0
  23 #
  24 # Unless required by applicable law or agreed to in writing, software
  25 # distributed under the License is distributed on an "AS IS" BASIS,
  26 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  27 # See the License for the specific language governing permissions and
  28 # limitations under the License.
  29
  30
  31 import os
  32 import kconfiglib
  33
  34 # Indentation to be used in the generated file
  35 INDENT = '    '
  36
  37 # Characters used when underlining section heading
  38 HEADING_SYMBOLS = '#*=-^"+'
  39
  40 # Keep the heading level in sync with api-reference/kconfig.rst
  41 INITIAL_HEADING_LEVEL = 2
  42 MAX_HEADING_LEVEL = 5
  43 OPTION_HEADING_LEVEL = 6
  44
  45 def print_menu_contents(title, items, heading_level, breadcrumbs, genindex):
  46     if not genindex:
  47         if title:
  48             print_section_heading(title, heading_level)
  49         if heading_level == INITIAL_HEADING_LEVEL+1:
  50             print_menu_contents(title, items, heading_level, breadcrumbs, True)
  51     for entry in items:
  52         if entry.is_menu():
  53             if len(breadcrumbs) > 0:
  54                 new_breadcrumbs = breadcrumbs + ' > ' + entry.get_title()
  55             else:
  56                 new_breadcrumbs = entry.get_title()
  57
  58             print_menu_contents(entry.get_title(), entry.get_items(),
  59                                 min(heading_level + 1, MAX_HEADING_LEVEL),
  60                                 new_breadcrumbs, genindex)
  61         elif genindex:
  62             print_item(entry, breadcrumbs)
  63         elif entry.is_choice():
  64             print_choice(entry, breadcrumbs)
  65         else:
  66             if len(entry.get_prompts()) == 0:
  67                 # Skip entries which can never be visible
  68                 continue
  69             # Currently this does not handle 'menuconfig' entires in any special way,
  70             # as Kconfglib offers no way of recognizing them automatically.
  71             print_option(entry, breadcrumbs)
  72         # Trailing newline after every option
  73         print
  74
  75 def print_choice(choice, breadcrumbs):
  76     print_option(choice, breadcrumbs)
  77     print
  78     print '%sAvailable options' % INDENT
  79     for opt in choice.get_symbols():
  80         # Format available options as a list
  81         print '%s- %s' % (INDENT * 2, opt.name)
  82
  83 def print_section_heading(title, heading_level):
  84     print title
  85     print HEADING_SYMBOLS[heading_level] * len(title)
  86     print
  87
  88 def print_option(opt, breadcrumbs):
  89     # add link target so we can use :envvar:`CONFIG_FOO`
  90     print '.. envvar:: CONFIG_%s' % opt.name
  91     print
  92     if len(opt.prompts) > 0:
  93         print '%s%s' % (INDENT, opt.prompts[0][0])
  94         print
  95     if opt.get_help() is not None:
  96         # Help text normally contains newlines, but spaces at the beginning of
  97         # each line are stripped by kconfiglib. We need to re-indent the text
  98         # to produce valid ReST.
  99         print '%s%s' % (INDENT, opt.get_help().replace('\n', '\n%s' % INDENT))
 100     print '%sFound in\n%s' % (INDENT, INDENT * 2 + breadcrumbs)
 101     print
 102
 103 def print_item(opt, breadcrumbs):
 104     print '- :envvar:`CONFIG_%s`' % opt.name
 105     print
 106
 107 def process_kconfig_file(kconfig_file, heading_level, breadcrumbs):
 108     if os.path.exists(kconfig_file):
 109         cfg = kconfiglib.Config(kconfig_file, print_warnings=True)
 110         print_menu_contents(None, cfg.get_top_level_items(), heading_level, breadcrumbs, False)
 111
 112 def print_all_components():
 113     heading_level = INITIAL_HEADING_LEVEL
 114     # Currently this works only for IDF components.
 115     # TODO: figure out if this can be re-used for documenting applications?
 116     components_path = os.path.join(os.path.curdir, '../..', 'components')
 117     for component_name in os.listdir(components_path):
 118         if component_name.startswith('.'):
 119             continue    # skip system thumbnail folders
 120
 121         kconfig_file_path = os.path.join(components_path, component_name, 'Kconfig')
 122
 123         process_kconfig_file(kconfig_file_path, heading_level, 'Component config')
 124         process_kconfig_file(kconfig_file_path + '.projbuild', heading_level, '')
 125
 126     kconfig_file_path = os.path.join(os.path.curdir, '../..', 'Kconfig.compiler')
 127     process_kconfig_file(kconfig_file_path, heading_level, '')
 128
 129 if __name__ == '__main__':
 130     print_all_components()