Feat/1759 doc codeblocks ci

[bogwi]

Problem

Hi, everyone.

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

Solution

Two commits were added. First introduced the mechanism, workflow and a script. The second - fixes documentation code blocks; those that did not mean to be run are skipped. My local CI, ./bin/run-doc-codeblocks --ci, is green. Total: 48 files, 139/139 blocks executed successfully. Artifacts were not committed, went lean.

Breaking Changes

None

Contributor License Agreement

• I have read and approved the CLA.

[greptile-apps]

Missing job-level timeout-minutes

The md-babel job has no timeout-minutes, so a hung or misbehaving code block can hold the self-hosted runner for GitHub's default 6-hour limit. All other jobs in this repo (e.g., ci.yml sets 60 minutes) have explicit timeouts.

Suggested change

	jobs:
	md-babel:
	md-babel:
	if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
	runs-on: self-hosted
	timeout-minutes: 30

[greptile-apps]

--ci flag is a no-op relative to the default

LANG_FILTER is already initialised to "python,sh,node" on line 9, and --ci sets it to the exact same value. The help text calls --ci "default; for CI runners", which is technically accurate but slightly confusing since invoking the script with no flags produces identical behaviour. The flag is harmless, but consider removing the redundant initialisation or having --ci be the only place this default is set to make the intent clearer.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[paul-nechifor]

Why the ifs? docs and README.md should always exist.

[bogwi]

if here is a harmless and defensive measure, but I can see it can look redundant.

[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).