jandelgado / jled / 31996100237

97%

push

github

Add missing files to docsite (#191)

* feat(doc-site): add doc:add / doc:link directives

The doc-site generator only rendered files from an example's root directory,
so examples/stm32cube_demo/Src/app.cpp never got a code box. Let an example's
README opt extra content in via inert HTML comments:

- <!-- doc:add <relpath> -->  render a subdirectory file as a code box, labeled
  with its full relative path, after the auto-discovered files.
- <!-- doc:link <relpath> --> link to a subdirectory; the generator emits a
  browsable index.html into the copied directory (GitHub Pages has no directory
  listing) and shows the link in a Directories section.

Paths are relative to the example dir; absolute paths and .. are rejected, and
missing or wrong-type targets are warned about and skipped. Directive comments
are stripped from the rendered README. Applied to examples/stm32cube_demo.

Also copy files a README links to (e.g. the top-level platformio.ini, which the
main README referenced but was never copied) to the mirrored path under the
version dir, so the relative links resolve. Only explicitly linked files inside
the repo are copied, keeping private and backup files out of the published site.

Finally, wrap the sidebar Install section in a sidebar_install block and override
it empty on example and directory pages, so Install no longer shows on examples.

* test(doc-site): add minimal pytest suite for generate_site.py

Add .tools/doc-site/test_generate_site.py, a self-contained uv script (pytest via
inline deps) covering parse_doc_directives and copy_linked_files, including a guard
that copy_linked_files copies only README-linked files and nothing else. Run it in
a separate test-generator CI job and from the top-level 'make test' target.

213 of 228 branches covered (93.42%)

Branch coverage included in aggregate %.

660 of 670 relevant lines covered (98.51%)

719.73 hits per line