import sys, os
import re
-from subprocess import Popen, PIPE
+import subprocess
import shlex
# Note: If extensions (or modules to document with autodoc) are in another directory,
os.system('python ../gen-dxd.py')
# Generate 'kconfig.inc' file from components' Kconfig files
+print "Generating kconfig.inc from kconfig contents"
kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
-os.system('python ../gen-kconfig-doc.py > ' + kconfig_inc_path + '.in')
-copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path)
+temp_sdkconfig_path = '{}/sdkconfig.tmp'.format(builddir)
+kconfigs = subprocess.check_output(["find", "../../components", "-name", "Kconfig"])
+kconfig_projbuilds = subprocess.check_output(["find", "../../components", "-name", "Kconfig.projbuild"])
+confgen_args = ["python",
+ "../../tools/kconfig_new/confgen.py",
+ "--kconfig", "../../Kconfig",
+ "--config", temp_sdkconfig_path,
+ "--create-config-if-missing",
+ "--env", "COMPONENT_KCONFIGS={}".format(kconfigs),
+ "--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(kconfig_projbuilds),
+ "--output", "docs", kconfig_inc_path
+]
+subprocess.check_call(confgen_args)
# http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format
#
+++ /dev/null
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-#
-# gen-kconfig-doc.py — generate Sphinx .rst file from Kconfig files
-#
-# This script iterates over Kconfig and Kconfig.projbuild files in
-# ESP-IDF component directories, and outputs documentation for these options
-# as ReST markup.
-# For each option in Kconfig file (e.g. 'FOO'), CONFIG_FOO link target is
-# generated, allowing options to be referenced in other documents
-# (using :ref:`CONFIG_FOO`)
-#
-# This script uses kconfiglib library to do all the work of parsing Kconfig
-# files: https://github.com/ulfalizer/Kconfiglib
-#
-# Copyright 2017 Espressif Systems (Shanghai) PTE LTD
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http:#www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-
-import os
-import kconfiglib
-
-# Indentation to be used in the generated file
-INDENT = ' '
-
-# Characters used when underlining section heading
-HEADING_SYMBOLS = '#*=-^"+'
-
-# Keep the heading level in sync with api-reference/kconfig.rst
-INITIAL_HEADING_LEVEL = 2
-MAX_HEADING_LEVEL = 5
-OPTION_HEADING_LEVEL = 6
-
-
-def print_menu_contents(title, items, heading_level, breadcrumbs):
- if title:
- print_section_heading(title, heading_level)
- for entry in items:
- if entry.is_menu():
- if len(breadcrumbs) > 0:
- new_breadcrumbs = breadcrumbs + ' > ' + entry.get_title()
- else:
- new_breadcrumbs = entry.get_title()
-
- print_menu_contents(entry.get_title(), entry.get_items(),
- min(heading_level + 1, MAX_HEADING_LEVEL),
- new_breadcrumbs)
- elif entry.is_choice():
- print_choice(entry, breadcrumbs)
- else:
- if len(entry.get_prompts()) == 0:
- # Skip entries which can never be visible
- continue
- # Currently this does not handle 'menuconfig' entires in any special way,
- # as Kconfglib offers no way of recognizing them automatically.
- print_option(entry, breadcrumbs)
- # Trailing newline after every option
- print
-
-def print_choice(choice, breadcrumbs):
- print_option(choice, breadcrumbs)
- print
- print '%sAvailable options:' % INDENT
- for opt in choice.get_symbols():
- # Format available options as a list
- print '%s- %s' % (INDENT * 2, opt.name)
-
-def print_section_heading(title, heading_level):
- print title
- print HEADING_SYMBOLS[heading_level] * len(title)
- print
-
-def print_option(opt, breadcrumbs):
- # add link target so we can use :ref:`CONFIG_FOO`
- print '.. _CONFIG_%s:' % opt.name
- print
- print_section_heading(opt.name, OPTION_HEADING_LEVEL)
- if len(opt.prompts) > 0:
- print '%s%s' % (INDENT, opt.prompts[0][0])
- print
- print '%s:emphasis:`Found in: %s`' % (INDENT, breadcrumbs)
- print
- if opt.get_help() is not None:
- # Help text normally contains newlines, but spaces at the beginning of
- # each line are stripped by kconfiglib. We need to re-indent the text
- # to produce valid ReST.
- print '%s%s' % (INDENT, opt.get_help().replace('\n', '\n%s' % INDENT))
-
-def process_kconfig_file(kconfig_file, heading_level, breadcrumbs):
- if os.path.exists(kconfig_file):
- cfg = kconfiglib.Config(kconfig_file, print_warnings=True)
- print_menu_contents(None, cfg.get_top_level_items(), heading_level, breadcrumbs)
-
-def print_all_components():
- heading_level = INITIAL_HEADING_LEVEL
- # Currently this works only for IDF components.
- # TODO: figure out if this can be re-used for documenting applications?
- components_path = os.path.join(os.path.curdir, '../..', 'components')
- for component_name in os.listdir(components_path):
- if component_name.startswith('.'):
- continue # skip system thumbnail folders
-
- kconfig_file_path = os.path.join(components_path, component_name, 'Kconfig')
-
- process_kconfig_file(kconfig_file_path, heading_level, 'Component config')
- process_kconfig_file(kconfig_file_path + '.projbuild', heading_level, '')
-
-if __name__ == '__main__':
- print_all_components()
# generated, allowing options to be referenced in other documents
# (using :ref:`CONFIG_FOO`)
#
-# Copyright 2017 Espressif Systems (Shanghai) PTE LTD
+# Copyright 2017-2018 Espressif Systems (Shanghai) PTE LTD
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
HEADING_SYMBOLS = '#*=-^"+'
# Keep the heading level in sync with api-reference/kconfig.rst
-INITIAL_HEADING_LEVEL = 2
-MAX_HEADING_LEVEL = 5
+INITIAL_HEADING_LEVEL = 3
+MAX_HEADING_LEVEL = len(HEADING_SYMBOLS)-1
def write_docs(config, filename):
""" Note: writing .rst documentation ignores the current value
- of any items. ie the --config option can be ignored. """
+ of any items. ie the --config option can be ignored.
+ (However at time of writing it still needs to be set to something...) """
with open(filename, "w") as f:
config.walk_menu(lambda node: write_menu_item(f, node))
node = node.parent
return result
+def format_rest_text(text, indent):
+ # Format an indented text block for use with ReST
+ text = indent + text.replace('\n', '\n' + indent)
+ # Escape some characters which are inline formatting in ReST
+ text = text.replace("*", "\\*")
+ text = text.replace("_", "\\_")
+ text += '\n'
+ return text
+
def write_menu_item(f, node):
if not node.prompt:
return # Don't do anything for invisible menu items
title = node.prompt[0]
# if no symbol name, use the prompt as the heading
- if is_menu:
+ if True or is_menu:
f.write('%s\n' % title)
f.write(HEADING_SYMBOLS[get_heading_level(node)] * len(title))
f.write('\n\n')
else:
- f.write('**%s**\n\n\n % title')
+ f.write('**%s**\n\n\n' % title)
if name:
f.write('%s%s\n\n' % (INDENT, node.prompt[0]))
# Help text normally contains newlines, but spaces at the beginning of
# each line are stripped by kconfiglib. We need to re-indent the text
# to produce valid ReST.
- f.write('%s%s\n' % (INDENT, node.help.replace('\n', '\n%s' % INDENT)))
+ f.write(format_rest_text(node.help, INDENT))
except AttributeError:
pass # No help
f.write('%s- %-20s (%s)\n' % (INDENT * 2, choice_node.prompt[0], choice_node.item.name))
if choice_node.help:
HELP_INDENT = INDENT * 2
- fmt_help = choice_node.help.replace('\n', '\n%s ' % HELP_INDENT)
- f.write('%s \n%s %s\n' % (HELP_INDENT, HELP_INDENT, fmt_help))
+ fmt_help = format_rest_text(choice_node.help, ' ' + HELP_INDENT)
+ f.write('%s \n%s\n' % (HELP_INDENT, fmt_help))
choice_node = choice_node.next
f.write('\n\n')
projects / esp-idf / commitdiff