gen_reference Namespace Reference

Functions
	collect_units ()
	collect_constants ()
	render_units_tables (rows, metric)
	render_constants_table (constants)
	supported_units_page (rows, metric)
	inject (text, name, body)
	build_readme (text, rows, metric, constants)
	main ()

Variables
	HERE = pathlib.Path(__file__).resolve().parent
	ROOT = HERE.parent.parent
str	INCLUDE = ROOT / "include" / "units"
str	UNITS_H = ROOT / "include" / "units.h"
str	README = ROOT / "README.md"
str	SUPPORTED_MD = HERE / "supported-units.md"
dict	SKIP = {"namePlural", "namespaceName", "abbreviation", "nameSingular"}
	UNIT_ADD
	WITH_METRIC = re.compile(r'\bUNIT_ADD_WITH_METRIC_PREFIXES\s*\‍(\s*(\w+)\s*,\s*(\w+)')
	CONSTANT = re.compile(r'\b([A-Za-z_]\w*)\s*\‍(\s*([0-9.eE+\-]+)\s*\‍)\s*;\s*///<\s*(.+?)\s*$')

Detailed Description

Generate the reference tables (supported units, physical constants) from the headers, and keep the
copies embedded in README.md in sync so they can never drift from the code.

Everything is derived from include/units/*.h and include/units.h, so re-run this whenever a unit or
constant is added, removed, or renamed:

  python3 docs/reference/gen_reference.py            # rewrite files + inject README blocks
  python3 docs/reference/gen_reference.py --check    # exit 1 if anything is out of date (for CI)

It (1) rewrites docs/reference/supported-units.md, (2) injects the supported-units and constants tables
into README.md between the marker comments:

  <!-- BEGIN generated: supported-units -->  ...  <!-- END generated: supported-units -->
  <!-- BEGIN generated: constants -->        ...  <!-- END generated: constants -->

Function Documentation

collect_constants()

collect_constants

(

)

Return [(symbol, value, doc), ...] in source order from the units::constants block in units.h.

collect_units()

collect_units

(

)

Return (rows, metric): rows[dim] = [(plural, abbrev), ...]; metric[dim] = {plural, ...}.

inject()

inject	(		text,
			name,
			body )

Replace the content between the BEGIN/END markers for `name`; error if the markers are absent.

render_units_tables()

render_units_tables	(		rows,
			metric )

The by-dimension unit tables (shared by the README block and the standalone reference page).

Variable Documentation

UNIT_ADD

gen_reference.UNIT_ADD

Initial value:

=  re.compile(
    r'\bUNIT_ADD(?:_WITH_METRIC_PREFIXES|_WITH_PLURAL_TAG|_WITH_METRIC_AND_BINARY_PREFIXES)?'
    r'\s*\‍(\s*(\w+)\s*,\s*(\w+)\s*,\s*(\w+)\s*,')