Feat/1759 doc codeblocks ci

[bogwi]

Problem

Hi, everyone.

This closes Execute documentation codeblocks in CI #1759 opened by @leshy .

Solution

Two strategies. First introduced the mechanism, workflow and a script. The second - improves present doc codeblocks for: missing imports, modules resolution, some blocks are wrapped to be run-able, those that did not mean to be run are skipped like illustrative one-liners or very heavy blocks, etc. This workflow is disabled for macos. This is a version 1 of the #1759 solution.

Breaking Changes

None

Contributor License Agreement

• I have read and approved the CLA.

[bogwi]

The last commit, 3be2ad5, addresses two previous minor ci run failures:
(a) trailing-whitespace, and
(b) astral's new "No more major and minor tags" policy from 8.0.0, use only immutable tags as versions.

The full ci should be green now and is safe to re-run.

If @paul-nechifor insists on "if" change - please say a word.

[leshy]

https://github.com/dimensionalOS/dimos/actions/runs/24695981801/job/72277385519?pr=1884

didn't investigate in detail, approved workflow run, currently fails in some weird way, is this related to it being an external PR?

[bogwi]

Tracing this: https://github.com/dimensionalOS/dimos/actions/runs/24711607201/job/72278865724?pr=1884.

What is actually failing

The job name is md-babel but the failure happens before ./bin/run-doc-codeblocks even runs. It fails on:

uv sync --extra dev --frozen --no-extra dds

That installs the project in editable mode which runs setuptools -> build_ext for the pybind11 extensions in setup.py. Pybind11’s auto_cpp_level() compiles a tiny probe (flagcheck.cpp) with c++ and -std=c++17 / 14 / 11. When all of those probes fail it gets:

RuntimeError: Unsupported compiler -- at least C++11 support is needed!

So this looks as a native C++ build environment problem on the runner not md-babel or markdown execution at all.

Two plausible ways to fix it:

1. use an environment known to compile dimos (as in ci.yml), or
2. to fix c++ / build tools on the self-hosted host.

The above last commit uses the same ci as in ci.yml. Also updated some docs to have no manipulation imports in CI.

[bogwi]

Updated workflow compiles dimos OK.

New commit addresses these that erred:
a) Marked the YOLO snippet as ```python skip.

b) Marked all replay and asset-dependent session=qb blocks in both quality_filter.md files as skip session=qb (left the two synthetic rx / quality_barrier examples runnable).

c) Marked all session=align Python blocks in both temporal_alignment.md files as skip session=align (embedded stays as documentation).

[bogwi]

md-babel-py is 1.1.4 now, supports --execution-timeout flag which I authored exactly for the purpose: https://github.com/leshy/md-babel-py/releases/tag/v1.1.4. Giving the recent > 60s (md-babe-py default) runs, timeout was increased to 120s. Done in 0707499

On the local machine, the current state of the docs fluctuates between 8 and 33 seconds, and not every block runs. The Golden Rule in codeblocks.md, as stated now, is: "All code blocks must be executable. Never write illustrative/pseudo code blocks. If you're showing an API usage pattern, create a minimal working example that actually runs. This ensures the documentation stays correct as the codebase evolves." However, this might not be possible to achieve.

Update in: 30a12a3

Greptile might flag this as Arbitrary code execution from fork PRs on self-hosted runner: github.event_name != 'pull_request' || github.event.pull_request.draft == false. To silence the bot - 0707499 was created, but it will not run on forks. @leshy, this needs your clarification as per #1759.

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

The base branch was changed.