wehub-resource-sync
99 lines
3.4 KiB
Python
99 lines
3.4 KiB
Python
# SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
#
|
|
# Generate RST documentation from extracted error codes.
|
|
# This script takes a CSV file (produced by err_codes_extract.py) and generates
|
|
# an RST file suitable for inclusion in Sphinx documentation.
|
|
#
|
|
# Usage:
|
|
# python err_codes_to_rst.py --csv errors.csv --output error_codes.inc
|
|
# python err_codes_to_rst.py --search-dirs components/ --output error_codes.inc
|
|
#
|
|
|
|
import argparse
|
|
import csv
|
|
import os
|
|
import sys
|
|
|
|
# Allow importing err_codes_extract from same directory
|
|
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
|
from err_codes_extract import extract_all # noqa: E402
|
|
from err_codes_extract import search_headers # noqa: E402
|
|
|
|
|
|
def read_csv_entries(csv_path: str) -> list[tuple[str, int, str]]:
|
|
"""Read error codes from a CSV file."""
|
|
entries: list[tuple[str, int, str]] = []
|
|
with open(csv_path, encoding='utf-8') as f:
|
|
reader = csv.DictReader(f)
|
|
for row in reader:
|
|
name = row['name']
|
|
value = int(row['value'])
|
|
comment = row.get('comment', '')
|
|
entries.append((name, value, comment))
|
|
return entries
|
|
|
|
|
|
def generate_rst(entries: list[tuple[str, int, str]]) -> str:
|
|
"""Generate RST content from error code entries.
|
|
|
|
Output format matches the existing esp_err_defs.inc generated by
|
|
gen_esp_err_to_name.py so it can be used as a drop-in replacement
|
|
in the docs build (included via ``.. include-build-file::``).
|
|
"""
|
|
lines: list[str] = []
|
|
|
|
# Sort by value: negative values first (ascending), then non-negative (ascending)
|
|
sorted_entries = sorted(entries, key=lambda e: (e[1], e[0]))
|
|
|
|
for name, value, comment in sorted_entries:
|
|
line = f':c:macro:`{name}` '
|
|
if value > 0:
|
|
line += f'**(0x{value:x})**'
|
|
else:
|
|
line += f'({value:d})'
|
|
if comment:
|
|
line += f': {comment}'
|
|
lines.append(line)
|
|
lines.append('')
|
|
|
|
return '\n'.join(lines)
|
|
|
|
|
|
def main() -> None:
|
|
parser = argparse.ArgumentParser(description='Generate RST documentation of ESP error codes')
|
|
parser.add_argument('--csv', default=None, help='Input CSV file with error codes (from err_codes_extract.py)')
|
|
parser.add_argument(
|
|
'--search-dirs', nargs='*', default=[], help='Directories to search recursively for header files'
|
|
)
|
|
parser.add_argument('--base-path', default=None, help='Base path for computing relative paths')
|
|
parser.add_argument('--output', required=True, help='Output RST file path')
|
|
|
|
args = parser.parse_args()
|
|
|
|
base_path = args.base_path
|
|
if base_path is None:
|
|
base_path = os.environ.get('IDF_PATH', os.getcwd())
|
|
|
|
if args.csv:
|
|
entries = read_csv_entries(args.csv)
|
|
elif args.search_dirs:
|
|
headers = search_headers(args.search_dirs, base_path)
|
|
err_codes = extract_all(headers, base_path)
|
|
entries = [(ec.name, ec.value, ec.comment) for ec in err_codes if ec.value is not None]
|
|
else:
|
|
print('Error: Specify either --csv or --search-dirs.', file=sys.stderr)
|
|
sys.exit(1)
|
|
|
|
rst_content = generate_rst(entries)
|
|
|
|
os.makedirs(os.path.dirname(os.path.abspath(args.output)), exist_ok=True)
|
|
with open(args.output, 'w', encoding='utf-8') as f:
|
|
f.write(rst_content)
|
|
|
|
print(f'Generated {args.output} with {len(entries)} error codes')
|
|
|
|
|
|
if __name__ == '__main__':
|
|
main()
|