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 :ref:`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
  46 def print_menu_contents(title, items, heading_level, breadcrumbs):
  47     if title:
  48         print_section_heading(title, heading_level)
  49     for entry in items:
  50         if entry.is_menu():
  51             if len(breadcrumbs) > 0:
  52                 new_breadcrumbs = breadcrumbs + ' > ' + entry.get_title()
  53             else:
  54                 new_breadcrumbs = entry.get_title()
  55
  56             print_menu_contents(entry.get_title(), entry.get_items(),
  57                                 min(heading_level + 1, MAX_HEADING_LEVEL),
  58                                 new_breadcrumbs)
  59         elif entry.is_choice():
  60             print_choice(entry, breadcrumbs)
  61         else:
  62             if len(entry.get_prompts()) == 0:
  63                 # Skip entries which can never be visible
  64                 continue
  65             # Currently this does not handle 'menuconfig' entires in any special way,
  66             # as Kconfglib offers no way of recognizing them automatically.
  67             print_option(entry, breadcrumbs)
  68         # Trailing newline after every option
  69         print
  70
  71 def print_choice(choice, breadcrumbs):
  72     print_option(choice, breadcrumbs)
  73     print
  74     print '%sAvailable options:' % INDENT
  75     for opt in choice.get_symbols():
  76         # Format available options as a list
  77         print '%s- %s' % (INDENT * 2, opt.name)
  78
  79 def print_section_heading(title, heading_level):
  80     print title
  81     print HEADING_SYMBOLS[heading_level] * len(title)
  82     print
  83
  84 def print_option(opt, breadcrumbs):
  85     # add link target so we can use :ref:`CONFIG_FOO`
  86     print '.. _CONFIG_%s:' % opt.name
  87     print
  88     print_section_heading(opt.name, OPTION_HEADING_LEVEL)
  89     if len(opt.prompts) > 0:
  90         print '%s%s' % (INDENT, opt.prompts[0][0])
  91         print
  92     print '%s:emphasis:`Found in: %s`' % (INDENT, breadcrumbs)
  93     print
  94     if opt.get_help() is not None:
  95         # Help text normally contains newlines, but spaces at the beginning of
  96         # each line are stripped by kconfiglib. We need to re-indent the text
  97         # to produce valid ReST.
  98         print '%s%s' % (INDENT, opt.get_help().replace('\n', '\n%s' % INDENT))
  99
 100 def process_kconfig_file(kconfig_file, heading_level, breadcrumbs):
 101     if os.path.exists(kconfig_file):
 102         cfg = kconfiglib.Config(kconfig_file, print_warnings=True)
 103         print_menu_contents(None, cfg.get_top_level_items(), heading_level, breadcrumbs)
 104
 105 def print_all_components():
 106     heading_level = INITIAL_HEADING_LEVEL
 107     # Currently this works only for IDF components.
 108     # TODO: figure out if this can be re-used for documenting applications?
 109     components_path = os.path.join(os.path.curdir, '../..', 'components')
 110     for component_name in os.listdir(components_path):
 111         if component_name.startswith('.'):
 112             continue    # skip system thumbnail folders
 113
 114         kconfig_file_path = os.path.join(components_path, component_name, 'Kconfig')
 115
 116         process_kconfig_file(kconfig_file_path, heading_level, 'Component config')
 117         process_kconfig_file(kconfig_file_path + '.projbuild', heading_level, '')
 118
 119 if __name__ == '__main__':
 120     print_all_components()