docs: add a warning to Setup & Dependencies docs about Git submodules

[Geff115]

Closes #343

Summary

Adds a warning admonition to the Setup & Dependencies documentation for contributors who clone the repository without the --recursive flag, leaving the third_party/stb submodule uninitialised.

Problem

When cloning without --recursive, third_party/stb is an empty directory on the host machine. Since the Docker dev container mounts the project directory, it sees the same empty folder, causing the Python bindings build to fail with:

fatal error: stb/stb_image.h: No such file or directory

This was discovered during setup in #341 (now reopened as another issue). The clone command in the docs already includes --recursive, but there was no guidance for contributors who had already cloned without it.

Fix

Added a :::warning admonition block directly beneath the clone command in docs/docs/contributing/setup-and-dependencies/index.md explaining the symptom and the recovery command:

git submodule update --init third_party/stb

Related

• Closes docs: add submodule initialization instructions to Setup & Dependencies page #343
• Requested by @Ryan-Millard in the fix(docker): copy stb submodule into dev image to fix Python bindings #341 thread

[coderabbitai]

Walkthrough

Added a warning admonition to the "Clone the repository" section explaining missing submodules when cloning without --recursive, including an expandable details block with tabbed git submodule update --init commands for third_party (all), third_party/stb (required), and third_party/dawn (optional).

Changes

Submodule initialization doc update

Layer / File(s)	Summary
Warning added docs/docs/contributing/setup-and-dependencies/index.md	Inserted a :::warning admonition under "Clone the repository" describing the failure mode when cloning without --recursive.
Remediation details docs/docs/contributing/setup-and-dependencies/index.md	Added a <details> block with tabbed commands showing git submodule update --init variants for third_party (all), third_party/stb (required), and third_party/dawn (optional).
Context / placement docs/docs/contributing/setup-and-dependencies/index.md	Placed the new content within the repository-clone guidance so contributors see submodule initialization steps immediately after cloning instructions.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰
I hopped through docs with care and cheer,
Placed a warning for clones that leer,
Tabs of fixes, short and clear,
Submodules found — the build draws near! 🥕

🚥 Pre-merge checks | ✅ 8

✅ Passed checks (8 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description is directly related to the changeset, explaining the problem, solution, and referencing the linked issue #343 that the PR addresses.
Linked Issues check	✅ Passed	The PR fully addresses issue #343 by adding a warning admonition with submodule initialization instructions to the documentation as requested.
Out of Scope Changes check	✅ Passed	All changes are in-scope documentation updates directly addressing the requirements in linked issue #343 with no extraneous modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
No Ai Slop Pr Description	✅ Passed	The PR description is specific and detailed, explaining what was changed and why with concrete references to issue #343, specific error messages, and recovery commands with no generic AI-generated boilerplate language.
No Strangely-Named Root Markdown Files	✅ Passed	The PR does not add any unconventional markdown files at the repository root. Only README.md, CONTRIBUTING.md, and CODE_OF_CONDUCT.md exist at root level, and the PR only modifies a documentation file within the docs/ directory structure.
Coderabbit Config Needs Update	✅ Passed	Documentation-only change to docs/docs/contributing/setup-and-dependencies/index.md adding a git submodule warning. No new languages, linter configs, file extensions, or CI tooling introduced.
Title check	✅ Passed	The title uses the 'docs:' prefix as required, is specific and descriptive, clearly indicating that documentation about Git submodules is being added to the Setup & Dependencies section.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

✨ Simplify code

• Create PR with simplified code

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/docs/contributing/setup-and-dependencies/index.md`:
- Around line 39-50: The warning admonition block closes immediately after the
fenced code block which violates markdownlint MD031; edit the admonition that
starts with ":::warning" and add a single blank line between the closing ```
fence and the closing ":::". Ensure there is exactly one empty line inserted
between the code fence and the admonition terminator so the block becomes:
opening ":::warning", the fenced code block, a blank line, then the closing
":::".

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 94eb9d55-6603-44da-9105-3d4850cd150e

📥 Commits

Reviewing files that changed from the base of the PR and between d5ab3d1 and 02a1cd0.

📒 Files selected for processing (1)

• docs/docs/contributing/setup-and-dependencies/index.md

📜 Review details

🧰 Additional context used

📓 Path-based instructions (2)

**/*.md

📄 CodeRabbit inference engine (.editorconfig)

**/*.md: Do not trim trailing whitespace in Markdown files
Use 2-space indentation for Markdown files
Do not enforce maximum line length for Markdown files

Files:

• docs/docs/contributing/setup-and-dependencies/index.md

docs/docs/**

⚙️ CodeRabbit configuration file

docs/docs/**: All documentation must follow Docusaurus conventions (docs/docs/ folder structure).
Do NOT suggest creating strangely-named markdown files at the repository root
(e.g. COMPREHENSIVE_TEST_REPORT.md, DELIVERABLES.md, SUMMARY.md).
New docs belong either as a dedicated Docusaurus category or integrated into an
existing category such as project-scripts. Verify valid frontmatter
(title, sidebar_label, etc.) and correct sidebar wiring.

Files:

• docs/docs/contributing/setup-and-dependencies/index.md

🧠 Learnings (3)

📓 Common learnings

Learnt from: CR
Repo: Ryan-Millard/Img2Num

Timestamp: 2026-05-04T09:43:57.481Z
Learning: Clone the repository using the `--recursive` flag to ensure the `third_party/stb` submodule is included

Learnt from: CR
Repo: Ryan-Millard/Img2Num

Timestamp: 2026-05-04T09:43:57.481Z
Learning: Use Docker dev environment for development instead of local setup

Learnt from: CR
Repo: Ryan-Millard/Img2Num

Timestamp: 2026-05-04T09:43:57.481Z
Learning: Use the `img2num` script wrapper (sh, bash, or shell commands) for running scripts inside the Docker environment

Learnt from: CR
Repo: Ryan-Millard/Img2Num

Timestamp: 2026-05-04T09:43:57.481Z
Learning: Run all CMake commands from the root of the project

Learnt from: CR
Repo: Ryan-Millard/Img2Num

Timestamp: 2026-05-04T09:43:57.481Z
Learning: Compile WebAssembly using Emscripten with `emcmake cmake` before using the JavaScript library and example apps

Learnt from: CR
Repo: Ryan-Millard/Img2Num

Timestamp: 2026-05-04T09:43:57.481Z
Learning: Install JavaScript dependencies using `pnpm install` before running documentation, packages, and example apps

Learnt from: CR
Repo: Ryan-Millard/Img2Num

Timestamp: 2026-05-04T09:43:57.481Z
Learning: Use `pnpm -F <workspace>` command to run scripts within specific workspace packages

Learnt from: CR
Repo: Ryan-Millard/Img2Num

Timestamp: 2026-05-04T09:43:57.481Z
Learning: Verify Git and Docker prerequisite installations using `git --version` and `docker --version`

📚 Learning: 2026-01-04T15:34:04.654Z

Learnt from: Ryan-Millard
Repo: Ryan-Millard/Img2Num PR: 146
File: docs/docs/reference/react/components/ThemeSwitch/tests.md:123-124
Timestamp: 2026-01-04T15:34:04.654Z
Learning: In Docusaurus documentation, relative directory links (e.g., ../ or ../../../hooks/useTheme) resolve to index.md within the target directory. Do not require or force linking to index.md explicitly; such relative links remain valid and should not be changed when reviewing docs under the docs directory.

Applied to files:

• docs/docs/contributing/setup-and-dependencies/index.md

📚 Learning: 2026-02-22T15:20:15.304Z

Learnt from: Ryan-Millard
Repo: Ryan-Millard/Img2Num PR: 263
File: docs/docs/internal/core/api-reference.md:13-13
Timestamp: 2026-02-22T15:20:15.304Z
Learning: In Docusaurus projects, Markdown files (*.md, *.mdx) may contain anchor tags with onClick={(e) => { e.preventDefault(); window.location.href = '...'; }} to force a full page navigation, bypassing React SPA routing for static/external paths. Treat this as intentional and do not flag it as redundant in docs contexts. Apply this guidance broadly to Markdown docs across the repository (not just the single file) and focus reviews on more impactful patterns such as accessibility, SEO, and navigation consistency.

Applied to files:

• docs/docs/contributing/setup-and-dependencies/index.md

🪛 markdownlint-cli2 (0.22.1)

docs/docs/contributing/setup-and-dependencies/index.md

[warning] 49-49: Fenced code blocks should be surrounded by blank lines

(MD031, blanks-around-fences)

[Ryan-Millard]

Thank you for the update! Our docs are definitely in need of some big updates.