From 101f06d23d6b0578fad2f2c9d7f9d44b332ad918 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 18 Aug 2026 07:15:05 +0000 Subject: [PATCH 1/2] fix: resolve MyST build warnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three warnings appear when running `myst build`: 1. basic_lessons/README.md "missing heading depth 2" — the page title is depth 1 but "Using this book" and "Contents" jumped straight to depth 3, skipping depth 2. Demote them to `##`. 2. lesson0_tutorial.md "Language is not defined for code block" — the verification {code-cell} had no language. Add `python` to the directive (``{code-cell} python``), which MyST records as the code language. 3. lesson2_tutorial.md "textEnv, Too few columns specified in the {array} column argument" — the 4x4 homogeneous transformation matrices H_a and H_a_b declared {array}{ccc} (3 columns) but have 4. Change to {cccc}. Verified with a full `myst build --execute --html`: no warnings remain. Co-authored-by: openhands --- basic_lessons/README.md | 4 ++-- basic_lessons/lesson0_tutorial.md | 2 +- basic_lessons/lesson2_tutorial.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/basic_lessons/README.md b/basic_lessons/README.md index 5dc7aa4..feab50e 100644 --- a/basic_lessons/README.md +++ b/basic_lessons/README.md @@ -4,13 +4,13 @@ In this six-lesson tutorial, we start from the very basics of setting up your Py then cover scalar and matricial operations in Python using `numpy`, all the way until the basics of kinematic control. Until kinematic control, most is based on [@spong2020robot]. -# Using this book +## Using this book Each lesson is a [MyST text notebook](https://mystmd.org/guide/notebooks-with-markdown). Each lesson can be opened and executed with popular IDEs, such as [VSCode](https://code.visualstudio.com) and [PyCharm](https://www.jetbrains.com/pycharm/). The reader is expected to follow it sequentially. -# Contents +## Contents | Number | Title and Link | Content | diff --git a/basic_lessons/lesson0_tutorial.md b/basic_lessons/lesson0_tutorial.md index 63d804f..97ff198 100644 --- a/basic_lessons/lesson0_tutorial.md +++ b/basic_lessons/lesson0_tutorial.md @@ -71,7 +71,7 @@ pip install numpy matplotlib You can verify that the packages are correctly installed by running the cell below. -````{code-cell} +````{code-cell} python import numpy as np import matplotlib import matplotlib.pyplot as plt diff --git a/basic_lessons/lesson2_tutorial.md b/basic_lessons/lesson2_tutorial.md index cfdf0f4..d24c4ed 100644 --- a/basic_lessons/lesson2_tutorial.md +++ b/basic_lessons/lesson2_tutorial.md @@ -322,7 +322,7 @@ We can also perform pose transformations using sequential right multiplications For example, consider a translation in 3D along the _World_ frame, represented by the homogeneous transformation matrix below. -$$\mymatrix{H}^0_a = \mymatrix{H}_a = \left[\begin{array}{ccc} +$$\mymatrix{H}^0_a = \mymatrix{H}_a = \left[\begin{array}{cccc} 1 & 0 & 0 & 1 \\ 0 & 1 & 0 & 2 \\ 0 & 0 & 1 & 3 \\ @@ -331,7 +331,7 @@ $$\mymatrix{H}^0_a = \mymatrix{H}_a = \left[\begin{array}{ccc} Consider a rotation in 3D about the _current_ frame, represented by the homogeneous transformation matrix below. -$$\mymatrix{H}^a_b = \left[\begin{array}{ccc} +$$\mymatrix{H}^a_b = \left[\begin{array}{cccc} \cos{\theta_{ab}} & -\sin{\theta_{ab}} & 0 & 0 \\ \sin{\theta_{ab}} & \cos{\theta_{ab}} & 0 & 0 \\ 0 & 0 & 1 & 0 \\ From 57ce1151726eb14b312afa70105f601cb4c2f69d Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 18 Aug 2026 11:16:58 +0000 Subject: [PATCH 2/2] docs: note build-warning pitfalls in AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md content was already accurate against the current repo state; no corrections were needed. Added a short "Keeping the build warning-free" note under Building & Testing documenting the three MyST warning classes fixed in this PR, including the non-obvious point that a bare {code-cell} only warns for lessons referenced as .md (lesson 0) — lessons 1-5 are .ipynb-referenced and Jupyter carries the Python language. Co-authored-by: openhands --- AGENTS.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ecb75ec..f279cbc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -123,6 +123,22 @@ myst build --html - `--execute` runs all code cells and caches results in `_build/execute/` - `--html` produces HTML output in `_build/html/` +### Keeping the build warning-free + +The CI `build` job runs the real build, so keep it free of warnings. The three +warning classes seen so far (all fixed in #11): + +- **`missing heading depth N`** — a page jumps heading levels (e.g. `#` then + `###`, skipping `##`). Use consecutive depths. +- **`textEnv, Too few columns specified in the {array} column argument`** — a + `\begin{array}{...}` declares fewer columns than a row has. Match the spec to + the actual column count (e.g. a 4×4 matrix needs `{cccc}`, not `{ccc}`). +- **`Language is not defined for code block`** — a `{code-cell}` with no + language. Add `python` (``{code-cell} python``). Note this only surfaces for + lessons referenced in `myst.yml` as **`.md`** (currently lesson 0): lessons + 1–5 are referenced as **`.ipynb`**, where Jupyter carries the Python language, + so their bare `{code-cell}` directives are fine. + ### CI/CD The GitHub Actions workflow (`.github/workflows/notebook_to_html.yml`) runs on pushes to `main` and on pull requests: