Didactic documentation: theory everywhere, bilingual figures, setup diagrams, parameter tables (#77)
* docs: harden diagram engine per visual audit
- dim() draws real witness lines from the measured points to the offset
dimension line (the offset=0 path emitted zero-length lines); vertical
labels sit left of the line, clear of masts and figures
- env diagram: the 4 m dimension now measures the mic axis itself and
the flush-mounted label moved to the clear zone between masts
- tonality top view: the 1.00 m dimension connects face and microphone
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* docs: bilingual diagram variants (EN/ES x light/dark)
Every setup diagram is now emitted in four variants; Spanish strings
(including decimal commas) come from a translation table applied by the
SVG engine, and layouts were adjusted where the longer Spanish labels
collided (env titles, processing-chain box width, calibration output
label, tonality dimension label side).
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* docs: bilingual figure variants for the ES site (EN/ES x light/dark)
generate_graphs.py now emits every figure in four variants: a Spanish
translation table (~75 exact strings + parametrized patterns) is applied
to the figure's Text artists at savefig time, so the generator functions
stay single-language internally. Spanish output uses UNE terminology
(ponderación temporal, líneas isofónicas, fonios, ráfaga) and a uniform
decimal comma (annotations and tick labels included); code identifiers
and normative mode names (Fast/Slow/Impulse) stay untranslated. The ES
site pages now reference the _es/_es_dark variants (56 URLs). The ES set
passed a 10-figure visual audit (10/10 approved, no blockers).
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* docs: didactic calibration page - theory, setup diagram, stability figure, parameter table
Adds the sensitivity-factor derivation with the calibration-chain SVG,
a new autogenerated calibration_stability figure (stable vs 3% AM tone
against the IEC 60942:2017 class 1 deviation band; 4 language/theme
variants; the ES decimal-comma pass now preserves clause numbers like
5.3.3), and a full parameter table for calculate_sensitivity - EN and
ES in parity.
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* docs: SEL concept, Lden 24h profile and annotated TNR spectrum figures
Three new didactic figures for the levels guide, each in four
language/theme variants: sel_concept (pass-by event vs its Leq and the
equal-energy 1 s SEL block, dBFS mode), lden_profile (synthetic urban
24 h LAeq with colored day/evening/night bands and the +5/+10 weighted
period levels clearly separated from the composite Lden), and
tonality_spectrum (averaged Hann spectrum with the critical band, the
detected tone and the live TNR value vs its criterion, computed by the
library itself).
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* docs: didactic levels guide, theory extensions and refreshed why-phonometry
- levels guide (EN docs+site): energy-mean rationale for Leq, percentile
semantics for LN, SEL and noise-dose theory with the new figures
embedded, TNR critical-band explanation with the annotated spectrum,
Lden profile figure, and parameter tables (type/units/range/default)
for every level function including the spectrogram
- theory page: five new sections (G-weighting pole/zero derivation,
ISO 226 formulae, ECMA-418-1 TNR/PR math, event/dose metrics,
ISO 1996-1 descriptors) with cross-references to the guides
- why-phonometry: rewritten around the conformance-testing story with
the per-standard verification table and honest ecosystem positioning
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* docs: weighting/time-weighting theory and parameter tables; fix math-block delimiters
The physiological origin of A/C (inverted 40/100-phon contours, the four
IEC corner frequencies) and the exponential-detector derivation with the
tau semantics, each with full parameter tables. Display math inserted by
the docs expansion now always uses block-style $$ delimiters on their
own lines - mid-line multi-line $$ blocks silently derailed remark
parsing and truncated every heading after them (caught because the
built pages lost their anchor ids); also replaced a raw < in a table.
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* docs: processing-chain and multirate diagrams, filter-bank math, streaming patterns
- getting-started embeds the processing-chain diagram as a guided map of
the guides
- filter-banks gains the IEC 61260-1 base-10 band math (G, fm, band
edges), a new multirate-decimation diagram (d5, four language/theme
variants) and the full octavefilter/OctaveFilterBank parameter table
- block-processing gains the canonical real-time level-meter loop
(validated against the actual API - TimeWeighting is inherently
stateful) and a stateful-constraints table
- multichannel gains the accepted-shapes table
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* docs: Spanish parity for the didactic expansion
Every enriched page now has its Spanish twin: levels (theory, three new
figures via _es variants, six parameter tables), weighting and
time-weighting (curve-origin and exponential-detector sections),
filter-banks (fractional-band math, multirate diagram, full parameter
table - terminology unified on 'decimación'), getting-started
(processing-chain map), block-processing (real-time meter pattern and
stateful constraints), multichannel (shapes table), theory (five new
sections) and a full rewrite of why-phonometry around the conformance
story. API reference now covers all 27 public exports in EN and ES
(added ToneAssessment and CalibrationWarning rows). UNE terminology and
Spanish decimal commas throughout; site builds with all links valid.
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* docs: audited fixes - Spanish tick commas and multirate note
Final visual-audit round: the d5 diagram now shows the no-decimation
note on the 16 kHz row in both languages, and Spanish figures render
every numeric tick with a decimal comma (FixedFormatter sequences are
rewritten in place; set_xticklabels-style FuncFormatters and plain
linear ScalarFormatters are wrapped - the first naive wrapper broke
ScalarFormatter ticks entirely and was caught visually).
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* docs(site): language selector in the mobile header, scrollable display math
Custom Header component (default markup plus a compact icon-only
LanguageSelect visible below the md breakpoint, where Starlight hides
the whole right group behind the hamburger menu) and overflow-x on
katex-display so wide formulas scroll inside their box on phones.
Verified with Playwright at 390 px in EN and ES.
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
* fix: address review feedback on the didactic docs
- levels tables: spectrogram calibration_factor/dbfs marked constructor-
only, overlap range as 0 <= overlap < 1, composite hours constraints,
ln_levels shared-semantics row filled; ES translation leftovers and
the 'delante' typo fixed
- block-processing: y[..., -1] so the meter loop is multichannel-safe;
high_accuracy wording matches the real behavior (default resolves to
False, explicit True raises)
- API: CalibrationWarning row states the fs/validate preconditions (3 files)
- weighting: high_accuracy default column and oversampling claim made
precise (8x cap; silently ignored for G); ES row in parity
- filter-banks: 25 Hz relative bandwidth corrected to 0.024% of Nyquist
(EN/ES); verify_filter_class classes documented as 1/2/None
- generate_graphs: dropped the global plt.savefig monkey-patch - the
translation now runs inside themed_path(), which every generator
already calls at save time (verified output identical)
Claude-Session: https://claude.ai/code/session_013kkVt3nxi9svp1an28uHxf
feat(site): unified APA references, accessible video embeds and build optimization (#223)
* feat(site): unified per-page references from typed frontmatter
Pages can now declare their bibliography as a typed references list in
the frontmatter (docsSchema extension: standard, book, article, web and
report entries with DOI/URL fields). A MarkdownContent override renders
one localized APA-7 References section at the end of the article,
alphabetized, with the title carrying the link and the DOI rendered as
its own descriptive link, and the route middleware appends the matching
On this page entry. Custom UI strings ride Starlight's i18n collection
(EN/ES).
* feat(site): accessible video embed with a download link
Video.astro wraps the Tier-1 animation convention (preload none, poster,
reserved width/height, EN/ES x light/dark WebM variants resolved from
the clip basename and the page language) and adds the accessibility
layer: required accessible name and textual description (aria-label +
aria-describedby), a visible localized download link per theme variant,
an in-element textual fallback, an optional visible caption and no
autoplay. The theme switch now also covers the wrapping figure.
* fix(site): keep the programme-loudness page titles within 70 characters
html-validate's long-title rule caps document titles at 70 characters
and the page suffix pushed both languages over the limit. The ITU-R/UIT-R
qualifier moves out of the title (the description and body keep the full
designations).
* docs: pilot migration to frontmatter references and the video embed
Loudness, aircraft noise and psychoacoustic annoyance (EN and ES) move
their References and Standards prose into the typed frontmatter
bibliography, with verified publisher links for every entry (ISO/IEC and
Ecma catalogues, ICAO store, SAE, ECAC, doi.org). Loudness and surface
scattering become MDX and embed their animations through the Video
component. The pa11y audit gains the six migrated URLs.
* perf(site): recompress served raster images and parallelize page rendering
A postbuild step palette-quantizes PNGs and re-encodes JPEGs in dist/
(sources untouched, rewritten only when smaller): the social card drops
from 663 KiB to 337 KiB. Page rendering moves to four concurrent pages.
The build profile documents the ceiling: the content-sync phase cannot
be cached while starlight-links-validator is enabled, since the plugin
clears the content-layer cache so its link map sees every page.
* docs: changelog for the site references, video embed and build optimization
* fix(site): review pass over the references and video infrastructure
References: nothing rendered after a DOI (APA-7), the annotation moves
to its own line and auto-links bare URLs keeping trailing sentence
punctuation out of the link (restoring the IEC 61265:2018 and ECAC
documents-page links in the aircraft-noise notes and the ICA 2016 venue
gloss in the annoyance notes), the Spanish pages join the last author
with "y" instead of the ampersand per the Spanish adaptation of APA-7,
the injected heading gets the same hover anchor as authored headings,
journal volumes italicize with <i> instead of <cite>, undated entries
sort first and the unreachable author fallback now fails loudly.
Video: figcaption kept as the last figure child (valid HTML) and an id
override for repeated embeds. Image recompression: per-file failures
skip with the file named instead of failing the build, and
already-indexed PNGs are skipped so a manual postbuild re-run cannot
re-quantize. Stale autoplay wording removed from the theme CSS comment;
leftover double blank lines collapsed.
feat(site): unified APA references, accessible video embeds and build optimization (#223)
* feat(site): unified per-page references from typed frontmatter
Pages can now declare their bibliography as a typed references list in
the frontmatter (docsSchema extension: standard, book, article, web and
report entries with DOI/URL fields). A MarkdownContent override renders
one localized APA-7 References section at the end of the article,
alphabetized, with the title carrying the link and the DOI rendered as
its own descriptive link, and the route middleware appends the matching
On this page entry. Custom UI strings ride Starlight's i18n collection
(EN/ES).
* feat(site): accessible video embed with a download link
Video.astro wraps the Tier-1 animation convention (preload none, poster,
reserved width/height, EN/ES x light/dark WebM variants resolved from
the clip basename and the page language) and adds the accessibility
layer: required accessible name and textual description (aria-label +
aria-describedby), a visible localized download link per theme variant,
an in-element textual fallback, an optional visible caption and no
autoplay. The theme switch now also covers the wrapping figure.
* fix(site): keep the programme-loudness page titles within 70 characters
html-validate's long-title rule caps document titles at 70 characters
and the page suffix pushed both languages over the limit. The ITU-R/UIT-R
qualifier moves out of the title (the description and body keep the full
designations).
* docs: pilot migration to frontmatter references and the video embed
Loudness, aircraft noise and psychoacoustic annoyance (EN and ES) move
their References and Standards prose into the typed frontmatter
bibliography, with verified publisher links for every entry (ISO/IEC and
Ecma catalogues, ICAO store, SAE, ECAC, doi.org). Loudness and surface
scattering become MDX and embed their animations through the Video
component. The pa11y audit gains the six migrated URLs.
* perf(site): recompress served raster images and parallelize page rendering
A postbuild step palette-quantizes PNGs and re-encodes JPEGs in dist/
(sources untouched, rewritten only when smaller): the social card drops
from 663 KiB to 337 KiB. Page rendering moves to four concurrent pages.
The build profile documents the ceiling: the content-sync phase cannot
be cached while starlight-links-validator is enabled, since the plugin
clears the content-layer cache so its link map sees every page.
* docs: changelog for the site references, video embed and build optimization
* fix(site): review pass over the references and video infrastructure
References: nothing rendered after a DOI (APA-7), the annotation moves
to its own line and auto-links bare URLs keeping trailing sentence
punctuation out of the link (restoring the IEC 61265:2018 and ECAC
documents-page links in the aircraft-noise notes and the ICA 2016 venue
gloss in the annoyance notes), the Spanish pages join the last author
with "y" instead of the ampersand per the Spanish adaptation of APA-7,
the injected heading gets the same hover anchor as authored headings,
journal volumes italicize with <i> instead of <cite>, undated entries
sort first and the unreachable author fallback now fails loudly.
Video: figcaption kept as the last figure child (valid HTML) and an id
override for repeated embeds. Image recompression: per-file failures
skip with the file named instead of failing the build, and
already-indexed PNGs are skipped so a manual postbuild re-run cannot
re-quantize. Stale autoplay wording removed from the theme CSS comment;
leftover double blank lines collapsed.
feat(site): link sidebar group labels to their section landing pages (#212)
* feat(site): link sidebar group labels to their section landing pages
Replace the stock Starlight sidebar with a local override
(src/components/Sidebar.astro + SidebarSublist.astro, adapted from
upstream 0.41.3) that renders every group permanently expanded and,
when a group's first item carries attrs: { 'data-group-link': true },
consumes that entry and turns the group label itself into the link
(Overview-first convention). The separate Overview rows disappear from
the sidebar while the landing pages stay published, indexed and in the
prev/next chain. Groups without a landing page (Start, Reference and
the generated API sections) remain static headings, now without a
caret, and the collapsed flag has no effect.
The API sidebar generator marks reference/api the same way, so the
"API reference" label links to the index page. sidebar.css splits
typography and color rules, guards the color on
:not([aria-current='page']) so the accent pill keeps its inverted text
when a label link is the current page, and restores the accent
hover/focus feedback for label links.
* test: expect the linked API group entry in the sidebar fragment
* refactor(site): forward landing link attributes and flatten the sublist mapping
feat(site): link sidebar group labels to their section landing pages (#212)
* feat(site): link sidebar group labels to their section landing pages
Replace the stock Starlight sidebar with a local override
(src/components/Sidebar.astro + SidebarSublist.astro, adapted from
upstream 0.41.3) that renders every group permanently expanded and,
when a group's first item carries attrs: { 'data-group-link': true },
consumes that entry and turns the group label itself into the link
(Overview-first convention). The separate Overview rows disappear from
the sidebar while the landing pages stay published, indexed and in the
prev/next chain. Groups without a landing page (Start, Reference and
the generated API sections) remain static headings, now without a
caret, and the collapsed flag has no effect.
The API sidebar generator marks reference/api the same way, so the
"API reference" label links to the index page. sidebar.css splits
typography and color rules, guards the color on
:not([aria-current='page']) so the accent pill keeps its inverted text
when a label link is the current page, and restores the accent
hover/focus feedback for label links.
* test: expect the linked API group entry in the sidebar fragment
* refactor(site): forward landing link attributes and flatten the sublist mapping
docs(site): migrate every guide to typed references, accessible media components and prose-aligned figures (#224)
* docs(site): migrate signal-analysis and level guides to typed references
Levels, time weighting, frequency weighting, calibration, block
processing, spectral analysis, filter banks, multichannel, correlation
and GUM uncertainty (EN and ES) move their manual References and
Standards sections into the typed frontmatter bibliography with
verified catalogue links. Time weighting becomes MDX and embeds its
needle animation through the Video component. Media placement fixes
from the audit: the levels tonal-adjustment figure joins its
explanatory paragraph (and a residual duplicated code block goes
away), the time-weighting video and figure follow the Fast/Slow/
Impulse bullets, calibration's flow diagram follows its intro
paragraph and block-processing's diagram and figure each join their
own paragraph, applied in the GitHub docs and both site languages.
* feat(site): theme-aware figure component and first migration wave
ThemeImage.astro renders the light/dark figure pair from the light
variant URL and a single alt text, deriving the _dark twin and keeping
the exact markup the theme switch and the responsive width tiers key
on, with native lazy-loading (the page hero opts into eager). The
signal-analysis guides, the pilots, getting started and why-phonometry
(EN and ES, 130 figure pairs) migrate their hand-written pairs to it,
becoming MDX where needed.
* docs(site): migrate psychoacoustics and hearing guides to typed references
Sound quality, hearing threshold, noise-induced hearing loss,
occupational exposure, speech intelligibility, speech transmission,
tone audibility, tone prominence, impulse prominence and programme
loudness (EN and ES) move their manual References and Standards
sections into the typed frontmatter bibliography with verified
catalogue links, become MDX and migrate their figure pairs to
ThemeImage. Impulse prominence embeds the onset-detection animation
through the Video component. Media placement fixes from the audit,
applied in the GitHub docs and both site languages: the STIPA chain
diagram joins the direct-method snippet it draws (with a new intro
sentence), the onset-detection clip moves next to the 10 dB/s onset
criterion and the KI(P) figure joins the paragraph that reads it, the
NIPTS/HTLAN panel joins its worked example and the occupational Annex D
figure follows the welder snippet.
* docs(site): migrate building-acoustics insulation guides to typed references
Laboratory and field insulation, insulation prediction (EN 12354),
enclosed-space absorption, dynamic and transfer stiffness, mechanical
mobility and structure-borne power (EN and ES) move their manual
References and Standards sections into the typed frontmatter
bibliography with verified catalogue links, become MDX and migrate
their figure pairs to ThemeImage. Insulation prediction embeds the
flanking-paths animation through the Video component. Media placement
fixes from the audit, applied in the GitHub docs and both site
languages: the flanking video joins its junction paragraph and the
facade figure regains its code block, the delta-L and Kij figures join
their explanatory paragraphs, the airborne rig diagram and the
uncertainty rating figure join theirs, and the mobility test-bench
diagram follows its description.
* docs(site): migrate rooms and materials guides to typed references
Installed structure-borne sources, vibration sound power,
reverberation prediction, room acoustics, room noise, acoustic
materials, porous absorbers and FDTD simulation (EN and ES) move their
manual References and Standards sections into the typed frontmatter
bibliography with verified catalogue links, become MDX, migrate their
figure pairs to ThemeImage and embed their animations (sweep
deconvolution, comb filtering, Schroeder decay, standing-wave tube and
room modes) through the Video component. Media placement fixes from
the audit, applied in the GitHub docs and both site languages: the
comb-filter clip joins the correlated-positions bullet, the open-plan
decay figure joins its metrics snippet, the impedance-tube diagram
follows its transmission-loss equation, the ISO 12999-2 uncertainty
figure regains its code block and the FDTD barrier field moves to the
geometry section it illustrates.
* docs(site): migrate environment and transport guides to typed references
Outdoor propagation, sound power, intensity, wind-turbine noise,
rotorcraft noise, electroacoustics, human vibration and multiple-shock
vibration (EN and ES) move their manual References and Standards
sections into the typed frontmatter bibliography with verified
catalogue links; together with the aircraft-noise pilot they become
MDX, migrate their figure pairs to ThemeImage and embed their
animations (ground effect, barrier diffraction, two rooms with one
sound power, intensity scanning and instantaneous intensity) through
the Video component. Media placement fixes from the audit, applied in
the GitHub docs and both site languages: the two-rooms clip opens the
sound-power story and the p-p probe diagram joins the intensity
paragraph, the phasor clip gets its own introduction, the SAE
absorption, NPD and SEL-contour figures join their explaining
paragraphs, and the wind-turbine tonality and rotorcraft ground-effect
figures join theirs.
* docs(site): migrate underwater guides to typed references
Underwater acoustics metrics and underwater propagation (EN and ES)
move their manual References and Standards sections into the typed
frontmatter bibliography (the propagation page carries its sixteen
JASA-heavy citations with bare DOIs), become MDX, migrate their figure
pairs to ThemeImage and embed the SOFAR-ducting animation through the
Video component. Media placement fixes from the audit, applied in the
GitHub docs and both site languages: the metrics page reunites each
figure with its code block, and the propagation page unwinds its
inverted layout by moving all seven figures below the prose,
formulas or snippets that explain them.
* docs(site): migrate theory pages to typed references
The five theory chapters (signal analysis, perception, rooms and
buildings, environment and transport, vibration; EN and ES) move
their manual References sections into the typed frontmatter
bibliography, reusing the verified catalogue links of the guides for
the works they share.
* docs(site): finish the reference migration and widen the accessibility gate
Surface scattering joins the typed bibliography (its in-situ ISO 13472
parts and the ISO 9613-1 coefficient gain verified catalogue entries,
and the outdoor-propagation pointer moves to See also). The pa11y gate
gains six representative migrated pages across both languages, and the
changelog records the completed migration.
* docs: reunite the loudness specific-loudness media with their prose
Second review pass. The loudness guide's triple media stack unwinds in
the GitHub docs and both site languages: the specific-loudness
animation gains an introductory sentence and the pattern figure moves
after the usage snippet, next to its code block. The Spanish
electroacoustics entry adopts the UIT-R acronym the programme-loudness
guide already uses.
* docs(site): review fixes to Spanish reference notes
feat(site): unified APA references, accessible video embeds and build optimization (#223)
* feat(site): unified per-page references from typed frontmatter
Pages can now declare their bibliography as a typed references list in
the frontmatter (docsSchema extension: standard, book, article, web and
report entries with DOI/URL fields). A MarkdownContent override renders
one localized APA-7 References section at the end of the article,
alphabetized, with the title carrying the link and the DOI rendered as
its own descriptive link, and the route middleware appends the matching
On this page entry. Custom UI strings ride Starlight's i18n collection
(EN/ES).
* feat(site): accessible video embed with a download link
Video.astro wraps the Tier-1 animation convention (preload none, poster,
reserved width/height, EN/ES x light/dark WebM variants resolved from
the clip basename and the page language) and adds the accessibility
layer: required accessible name and textual description (aria-label +
aria-describedby), a visible localized download link per theme variant,
an in-element textual fallback, an optional visible caption and no
autoplay. The theme switch now also covers the wrapping figure.
* fix(site): keep the programme-loudness page titles within 70 characters
html-validate's long-title rule caps document titles at 70 characters
and the page suffix pushed both languages over the limit. The ITU-R/UIT-R
qualifier moves out of the title (the description and body keep the full
designations).
* docs: pilot migration to frontmatter references and the video embed
Loudness, aircraft noise and psychoacoustic annoyance (EN and ES) move
their References and Standards prose into the typed frontmatter
bibliography, with verified publisher links for every entry (ISO/IEC and
Ecma catalogues, ICAO store, SAE, ECAC, doi.org). Loudness and surface
scattering become MDX and embed their animations through the Video
component. The pa11y audit gains the six migrated URLs.
* perf(site): recompress served raster images and parallelize page rendering
A postbuild step palette-quantizes PNGs and re-encodes JPEGs in dist/
(sources untouched, rewritten only when smaller): the social card drops
from 663 KiB to 337 KiB. Page rendering moves to four concurrent pages.
The build profile documents the ceiling: the content-sync phase cannot
be cached while starlight-links-validator is enabled, since the plugin
clears the content-layer cache so its link map sees every page.
* docs: changelog for the site references, video embed and build optimization
* fix(site): review pass over the references and video infrastructure
References: nothing rendered after a DOI (APA-7), the annotation moves
to its own line and auto-links bare URLs keeping trailing sentence
punctuation out of the link (restoring the IEC 61265:2018 and ECAC
documents-page links in the aircraft-noise notes and the ICA 2016 venue
gloss in the annoyance notes), the Spanish pages join the last author
with "y" instead of the ampersand per the Spanish adaptation of APA-7,
the injected heading gets the same hover anchor as authored headings,
journal volumes italicize with <i> instead of <cite>, undated entries
sort first and the unreachable author fallback now fails loudly.
Video: figcaption kept as the last figure child (valid HTML) and an id
override for repeated embeds. Image recompression: per-file failures
skip with the file named instead of failing the build, and
already-indexed PNGs are skipped so a manual postbuild re-run cannot
re-quantize. Stale autoplay wording removed from the theme CSS comment;
leftover double blank lines collapsed.