EzyCad documentation style

Use this guide when editing user-facing Markdown in docs/ (usage.md, usage-*.md, scripting.md, plus building-occt.md, bugs.md, the two style guides, etc.) and the root README.md / CHANGELOG.md. For C++ in src/, see ezycad_code_style.md.

Published HTML: https://ezycad.readthedocs.io/ (/en/latest/ tracks main). Build plumbing is described in readthedocs.md.

Canonical files (edit these)

All live together under the single docs/ folder:

File

Purpose

usage.md

Main usage guide

usage-sketch.md

2D sketching

usage-settings.md

Settings pane and JSON

usage-occt-view.md

3D viewer (OCCT)

scripting.md

Lua / Python consoles

building-occt.md

Building Open CASCADE (desktop + WebAssembly)

bugs.md

Known issues / sharp edges

ezycad_code_style.md

C++ style (in src/)

ezycad_doc_style.md

This file – Markdown / user docs style

README.md (root)

Project overview

CHANGELOG.md (root)

Release notes (Keep a Changelog)

Writing conventions

  • Audience: Machinists and hobby CAD users; prefer plain language and short steps.

  • Headings: Use ## / ### for sections Sphinx/MyST can index; keep a stable Table of Contents in usage.md when adding major sections.

  • Keyboard shortcuts: Use <kbd>Tab</kbd>, <kbd>Ctrl</kbd>+<kbd>Z</kbd>, etc. They render on Read the Docs via MyST.

  • Tables: GFM pipe tables are fine on Read the Docs.

  • Cross-links: Link other guides as usage-sketch.md, usage-settings.md#view-menu, or #anchor within the same file. Prefer anchors that match heading text (MyST slugifies headings for URLs).

  • Encoding: The ASCII-only rule in ezycad_code_style.md applies to src/, not to these guides; Unicode in user docs is acceptable when it helps clarity.

Images

Kind

Path

Syntax

Toolbar icons

res/icons/Name.png

![alt](res/icons/Name.png)

Screenshots / diagrams

images/name.png

![alt](images/name.png)

Rules:

  • Use Markdown image syntax only. Do not use raw HTML <img src="..."> — Sphinx will not rewrite the path and images will break on Read the Docs.

  • Commit new screenshots under docs/images/.

  • Commit toolbar icons under res/icons/.

  • After changes, run sphinx-build -b html -W docs docs/_build locally, or rely on the Read the Docs build (it has fail_on_warning: true).

Build and CI (reference)

Everything documentation-related now lives under the single docs/ folder at the repository root. This is the only directory contributors need to care about for docs.

Item

Location

Read the Docs config

.readthedocs.yaml (at repo root)

Sphinx config + content

docs/conf.py, docs/index.rst, all the *.md guides

Python deps

docs/requirements.txt

GitHub Actions verification

.github/workflows/docs.yml

 
pip install -r docs/requirements.txt
sphinx-build -b html -W docs docs/_build