Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge branch 'bugfix/doc_macro_definitions' into 'master'

Browse source 
doc: Fix macro definitions for different targets

See merge request espressif/esp-idf!8999
This commit is contained in:
Angus Gratton 2020-06-12 16:37:41 +08:00
commit 1c09cb6769
6 changed files with 36 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
components/driver/include/driver/uart.h
View file

@ -858,7 +858,6 @@ esp_err_t uart_set_loop_back(uart_port_t uart_num, bool loop_back_en);
* @param always_rx_timeout_en Set to false enable the default behavior of timeout interrupt,
* set it to true to always trigger timeout interrupt.
*
* * @return None
*/
void uart_set_always_rx_timeout(uart_port_t uart_num, bool always_rx_timeout_en);

6
components/soc/include/hal/adc_types.h
View file

@ -108,7 +108,7 @@ typedef struct {
If (channel > ADC_CHANNEL_MAX), The data is invalid. */
uint16_t unit: 1; /*!<ADC unit index info. 0: ADC1; 1: ADC2. */
} type2; /*!<When the configured output format is 11bit. `ADC_DIGI_FORMAT_11BIT` */
uint16_t val;
uint16_t val; /*!<Raw data value */
};
} adc_digi_output_data_t;
@ -191,10 +191,10 @@ typedef struct {
1: input voltage * 1/1.34;
2: input voltage * 1/2;
3: input voltage * 1/3.6. */
uint8_t reserved: 2; /*!< reserved0 */
uint8_t reserved: 2; /*!< reserved0 */
uint8_t channel: 4; /*!< ADC channel index. */
};
uint8_t val;
uint8_t val; /*!< Raw entry value */
};
} adc_digi_pattern_table_t;

3
docs/Doxyfile
View file

@ -341,7 +341,4 @@ GENERATE_RTF = NO
## Skip distracting progress messages
##
QUIET = YES
## Log warnings in a file for further review
##
WARN_LOGFILE = "doxygen-warning-log.txt"

6
docs/conf_common.py
View file

@ -58,6 +58,10 @@ extensions = ['breathe',
'extensions.toctree_filter',
'extensions.list_filter',
# Note: order is important here, events must
# be registered by one extension before they can be
# connected to another extension
'idf_extensions.include_build_file',
'idf_extensions.link_roles',
'idf_extensions.build_system',
@ -65,11 +69,11 @@ extensions = ['breathe',
'idf_extensions.gen_toolchain_links',
'idf_extensions.gen_version_specific_includes',
'idf_extensions.kconfig_reference',
'idf_extensions.gen_defines',
'idf_extensions.run_doxygen',
'idf_extensions.gen_idf_tools_links',
'idf_extensions.format_idf_target',
'idf_extensions.latex_builder',
'idf_extensions.gen_defines',
'idf_extensions.exclude_docs',
# from https://github.com/pfalcon/sphinx_selective_exclude

18
docs/idf_extensions/gen_defines.py
View file

@ -7,6 +7,7 @@
import glob
import os
import pprint
import subprocess
import re
@ -32,6 +33,11 @@ def generate_defines(app, project_description):
for soc_header in soc_headers:
defines.update(get_defines(soc_header, sdk_config_path))
# write a list of definitions to make debugging easier
with open(os.path.join(app.config.build_dir, "macro-definitions.txt"), "w") as f:
pprint.pprint(defines, f)
print("Saved macro list to %s" % f.name)
add_tags(app, defines)
app.emit('idf-defines-generated', defines)
@ -48,8 +54,14 @@ def get_defines(header_path, sdk_config_path):
for line in processed_output.split("\n"):
line = line.strip()
m = re.search("#define ([^ ]+) ?(.*)", line)
if m and not m.group(1).startswith("_"):
defines[m.group(1)] = m.group(2)
if m:
name = m.group(1)
value = m.group(2)
if name.startswith("_"):
continue # toolchain macro
if (" " in value) or ("=" in value):
value = "" # macros that expand to multiple tokens (ie function macros) cause doxygen errors, so just mark as 'defined'
defines[name] = value
return defines
@ -69,4 +81,4 @@ def setup(app):
app.connect('idf-info', generate_defines)
app.add_event('idf-defines-generated')
return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'}
return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.2'}

36
docs/idf_extensions/run_doxygen.py
View file

@ -21,27 +21,9 @@ ALL_KINDS = [
def setup(app):
# The idf_build_system extension will emit this event once it
app.connect('idf-info', generate_doxygen)
return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'}
def _parse_defines(header_path, sdk_config_path):
defines = {}
# Note: we run C preprocessor here without any -I arguments (except "sdkconfig.h"), so assumption is
# that these headers are all self-contained and don't include any other headers
# not in the same directory
print("Reading macros from %s..." % (header_path))
processed_output = subprocess.check_output(["xtensa-esp32-elf-gcc", "-I", sdk_config_path,
"-dM", "-E", header_path]).decode()
for line in processed_output.split("\n"):
line = line.strip()
m = re.search("#define ([^ ]+) ?(.*)", line)
if m and not m.group(1).startswith("_"):
defines[m.group(1)] = m.group(2)
return defines
# The idf_build_system extension will emit this event once it has generated documentation macro definitions
app.connect('idf-defines-generated', generate_doxygen)
return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.2'}
def generate_doxygen(app, defines):
@ -57,8 +39,16 @@ def generate_doxygen(app, defines):
})
doxyfile = os.path.join(app.config.docs_root, "Doxyfile")
print("Running doxygen with doxyfile {}".format(doxyfile))
# note: run Doxygen in the build directory, so the xml & xml_in files end up in there
subprocess.check_call(["doxygen", doxyfile], env=doxy_env, cwd=build_dir)
# It's possible to have doxygen log warnings to a file using WARN_LOGFILE directive,
# but in some cases it will still log an error to stderr and return success!
#
# So take all of stderr and redirect it to a logfile (will contain warnings and errors)
logfile = os.path.join(build_dir, "doxygen-warning-log.txt")
with open(logfile, "w") as f:
# note: run Doxygen in the build directory, so the xml & xml_in files end up in there
subprocess.check_call(["doxygen", doxyfile], env=doxy_env, cwd=build_dir, stderr=f)
# Doxygen has generated XML files in 'xml' directory.
# Copy them to 'xml_in', only touching the files which have changed.