Audit pass 5: complete API reference and theory coverage (#114)
* docs: complete API reference and theory coverage
Audit batch 5 — the reference layer catches up with everything merged
since PR ~#95:
API reference (repo + site EN/ES): from 152 to 351 documented names,
verified complete against phonometry.__all__ (the six callable aliases
and four PEP 562 renamed names live in a deprecated-aliases note
instead of rows). All quoted example outputs are computed, not written
by hand. Also deduplicates two warning rows in the site mirror, updates
the .plot() availability note (38 result classes) and escapes the
math | characters that broke GFM table rendering.
Theory (repo + site EN/ES): sections for the sixteen standards the
document did not cover - NT ACOU 112, ANSI S3.5 SII, ISO 389-7/7029,
ISO 1999, ANSI S12.2, ISO 17497-1/2, ISO 13472-1/2, ISO 11654,
ISO 9053-1/2, ISO 10534-1/2 + ASTM E2611, ISO 8041-1 + ISO 2631-1/2 +
ISO 5349 + Directive 2002/44/EC, ISO 2631-5, EN 12354-6, ISO 3745,
ISO 9614-3, DIN 45692 and the GUM + Supplement 1 - each with its
formulas, normative constants taken from the code, design decisions and
validation anchors, cross-linked to its guide. EN site mirror verified
byte-identical to the repo file modulo frontmatter; ES translated with
the site's conventions.
* docs: Spanish decimal fixes in the new reference content
- the described |H| output list in the ES API reference uses comma
decimals like the surrounding prose (Gemini)
- the two LaTeX exponents in the new ES theory sections use the {,}
convention (Gemini)
The def.: literals keep points deliberately - they are Python default
literals and the file's ~150 existing rows already follow that style;
the legacy point-decimals in pre-existing ES theory LaTeX belong to the
systematic {,} migration scheduled in the bilingual batch.
Audit pass 6: split the three overloaded guides (#115)
* docs: split the three overloaded guides
Audit batch 6 - reorganization with full content preservation (verified
line-by-line against HEAD across the three surfaces):
- room-acoustics (1096 lines) keeps ISO 18233 + ISO 3382-1/2/3 + ISO 354
measurement; the building half (ISO 16283 + ISO 717, ISO 10140,
EN 12354-1/2, ISO 12999-1) moves to a new docs/building-acoustics.md
built from the site's existing split, resolving the repo/site
asymmetry. The flanking figure is reunited with its <details> code and
flanking_path is introduced before it is referenced (audit fixes), on
all three surfaces.
- psychoacoustics extracts STI/STIPA to speech-transmission.md
(paralleling speech-intelligibility.md) with STI-vs-SII disambiguation
boxes on the three pages involved; ISO 226 moves into psychoacoustics
where its perception content belongs, fixing its stale 'upcoming
feature' sentence.
- levels extracts occupational-exposure.md (ISO 9612) and
tone-prominence.md (ECMA-418-1), keeping Leq/LN/peak/SEL/Lden and the
spectrogram.
Indexes, sidebar, theory/guide cross-links (~40 edits in 19 files) and
the llms.txt generator PAGES list follow the moves; the four extracted
topics now survive into llms-full.txt instead of dropping out.
* docs: Spanish grammar fixes in the split guides
- 'función de conveniencia' instead of the false friend 'comodidad'
for convenience function (Gemini)
- plural agreement 'estrategias basadas' at the two flagged sites
(Gemini); the remaining 'basada' occurrences are correct singular
agreements ('medición basada en tareas', 'la estrategia basada...')
* docs: address second-round review on the splits
- flanking_path() gains its own parameter table (with the kij_min
Formula E.4 floor contract) in the building guide, all three surfaces
(CodeRabbit)
- the flanking figure snippet explicitly annotates its reuse of paths/
res from the snippet above; the speech-transmission figure snippet is
now fully self-contained (imports + fs) on all surfaces (CodeRabbit)
- ISO 10140-3 joins the laboratory standards footer (CodeRabbit)
- the Speech Intelligibility guide joins llms.txt (regenerated) and the
root README table (CodeRabbit)
Audit pass 4c: final identifier sweep against the naming convention (#113)
* refactor: final identifier sweep against the naming convention
Audit batch 4c — the remaining non-conforming identifiers, closing the
library-wide rename batch:
- public constants drop the unit suffix (units belong in docstrings):
OCTAVE_BANDS, THIRD_OCTAVE_BANDS (absorption_rating) and
BASE_PLATE_BANDS (scattering_diffusion), with PEP 562 __getattr__
shims in the home modules and at the package root; plain import stays
warning-free (verified with -W error)
- sii.BAND_CENTRES -> BAND_CENTERS (American spelling, module shim);
the private road_absorption centres constant renames directly
- ExposureWarning -> OccupationalExposureWarning; the module
__getattr__ returns the same class object so isinstance/except and
warning filters via the old name keep matching
- multiple_shock_vibration reuses hearing.SEXES instead of a private
duplicate
- tests/reference_data.py families gain their standard designations
(ANSIS3_5_*, ANSIS12_2_*, NTACOU112_*, ISO7029_*, ISO389_7_*)
- misleading test files renamed: test_parametrized_signals.py (it never
tested parametric_filters) and test_loudness_contours.py (1:1 with
its module); scripts/gen_llms.py -> generate_llms.py (workflow and
Makefile updated)
- conformance internals catch up (_chk_impulse_*) and an internal use
of the deprecated expanded_uncertainty alias is migrated
Flagged and deliberately left: REFERENCE_DURATION_S (the mixed-units
carve-out applies - seconds and hours coexist in the exposure API) and
the private British 'unfavourable' constants (ISO 717/11654 normative
wording; private tables are named after the standard).
Six new alias tests (root and module access, class identity, the
AttributeError path).
* test: anchor the renamed band tables value-by-value
The tests around the renamed constants asserted lengths or spot values;
they now pin every element (nominal one-third-octave and base-plate
bands, the SII band centers, and the per-impulse Formula 1 values),
verified against the code, so an accidental table edit cannot pass
(Gemini).