Skip to content

docs: comprehensive v3 documentation rewrite#582

Merged
fgmacedo merged 21 commits intodevelopfrom
docs/v3-rewrite
Feb 24, 2026
Merged

docs: comprehensive v3 documentation rewrite#582
fgmacedo merged 21 commits intodevelopfrom
docs/v3-rewrite

Conversation

@fgmacedo
Copy link
Owner

@fgmacedo fgmacedo commented Feb 24, 2026

Summary

  • New pages: tutorial, statechart (compound/parallel/history), events, error handling, validations, behaviour
  • Rewritten pages: actions, guards, listeners, concepts, states, transitions, processing model, async, diagram, weighted transitions
  • Release docs: rewritten 3.0.0 release notes, AI-friendly upgrade guide (2.x → 3), cleaned up release index
  • Landing page: docs index now renders README.md directly as the landing page
  • Bug fix: validator exceptions now always propagate (never silently converted to error.execution)
  • Tests: added comprehensive validator test suite (tests/test_validators.py)

Test plan

  • Full test suite passes (1325 passed, 1 skipped, 44 xfailed)
  • Sphinx build succeeds with no new warnings
  • All code examples in docs are working doctests
  • Visual review of built HTML documentation

fgmacedo and others added 21 commits February 22, 2026 11:12
Rewrite core documentation pages for the v3 release with SCXML-compliant
statechart semantics, consistent narrative, and testable doctests throughout.

New pages:
- concepts.md: hybrid narrative + reference overview of states, transitions,
  events, and actions
- quickstart.md: progressive tutorial from flat FSM to full statechart using
  a coffee shop domain
- events.md: extracted from transitions.md; declaring, triggering, send vs
  raise_(), delayed, done.state, error events
- error_handling.md: error.execution lifecycle, block-level catching, cleanup
- validations.md: consolidated validation checks (reachability, trap states,
  final state constraints)

Rewritten pages:
- actions.md: execution order table with all 9 groups, SCXML exit/enter
  semantics for compounds, full invoke documentation, DI with
  previous/new_configuration, priority within groups
- states.md: pedagogical intro, parameters table, removed autoclass dump and
  deprecated current_state references
- transitions.md: extracted events, added from_(), from_.any(), multiple
  targets, cross-boundary, transition priority
- index.md: reorganized toctree into Getting Started, Core Concepts, Engine,
  Advanced, Reference sections

Minor updates: processing_model.md labels, models.md, guards.md, listeners.md,
async.md, diagram.md, integrations.md, statecharts.md, conf.py seealso links.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Instead of showing is_terminated as a bare syntax check after a flat
example (where it adds no value), introduce it in the parallel states
section where its purpose is clear: with compound and parallel states,
completion depends on the structure, not a single final state.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rename quickstart.md → tutorial.md and update title to "Tutorial" to
distinguish the progressive learning guide from the README showcase.

Add "Checking completion with is_terminated" section after parallel
states, explaining why is_terminated matters for compound/parallel
structures and showing the idiomatic queue-consumption loop pattern.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New files:
- statechart.md (Core Concepts): StateChart instance runtime API —
  creating instances, sending events (send/raise_/delayed), querying
  events (allowed_events/enabled_events), querying configuration,
  checking termination (is_terminated), managing listeners, class attrs.
- behaviour.md: extracted behavior flags from statecharts.md — focused
  on StateChart vs StateMachine comparison table, flag explanations, and
  gradual migration. Removed duplicated SCXML feature docs (compound,
  parallel, history, etc.) already covered in states.md/events.md.

Reorganized events.md:
- Progressive narrative: declaring → identity (id vs name) → triggering
  (bridge to statechart.md) → event parameter → automatic events
  (done.state, error.execution) → dot-notation naming conventions.
- Removed duplicated send/raise_/delayed content (now in statechart.md).
- Added multi-event parameter docs (list and space-separated strings).
- Consolidated done_state_ and error_ naming conventions in one section.

Updated cross-references in actions.md, tutorial.md, processing_model.md,
states.md, and index.md toctree.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Reorganize transitions.md with progressive narrative and consistent
order-processing domain across all examples.

Narrative order: declaring → parameters table → combining with | →
from_()/from_.any() → self/internal transitions → eventless →
cross-boundary → priority.

Key improvements:
- All examples use order/e-commerce domain (replacing disconnected
  LotR and generic examples)
- Self and internal transitions unified in one section with practical
  contrast (RetryOrder vs OrderCart)
- from_.any() with equivalent compound state alternative, side-by-side
  diagrams showing both approaches
- Equivalent state topology between flat and compound examples

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Reorder sections: execution order → dependency injection → binding →
  generic callbacks → preparing events → return values
- Move DI before binding so readers understand injection before examples
- Remove ~230 lines of invoke content duplicated from invoke.md, replace
  with seealso cross-reference
- Add `error` parameter to DI available parameters table with ref to
  error-execution
- Add API cross-reference links (class directives) in parameters table
- Promote generic callbacks to ## with tip about listeners
- Add `on_invoke_state` to execution order table and generic callbacks
- Fix error_handling.md seealso reference: statecharts → behaviour

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…execution

Validators operate in the transition-selection phase, not the execution
phase. A validator rejecting is semantically "this transition should not
happen" — not "something failed during execution". Converting the
exception to error.execution conflated these two concepts.

Engine change: pass on_error=None for validators in _conditions_match()
(both sync and async), so exceptions always propagate to the caller
regardless of error_on_execution.

- Add 28 dedicated validator tests (14 scenarios × sync/async via
  sm_runner): propagation, multiple validators, combined with cond,
  no error.execution trigger, no fallthrough
- Rewrite guards.md: progressive narrative, conditions with kwargs
  (PriorityRouter), validator propagation semantics, contrast with
  error.execution, rename title to "Conditions"
- Remove now-unnecessary error_on_execution=False from conftest fixture
  and issue509 test
Reorganize listeners.md for a natural learning flow:
- Intro with architectural insight (StateChart/models are listeners)
- Defining a listener (any object with matching methods)
- Class-level declarations first (declarative, most common)
- Constructor attachment second, runtime add_listener third
- setup() protocol promoted to its own section
- All examples self-contained (no external test imports)
- Add missing StateChart and Listeners sections to match Core Concepts
  toctree
- Move quick reference table to top as orientation map with ref links
- Update condition reference from "validators and guards" to "conditions"
…arrative

Reorganize the processing model page for clarity:
- Add W3C SCXML citation and compliance mention in intro
- Lead with macrosteps/microsteps before the practical example
- Align microstep phases with actions.md execution order (8 groups)
- Move RTC example after concepts are established
- Rename "Continuous state machines" to "Chaining transitions"
- Fix misleading "atomically" wording in microstep description
- Fix unclosed seealso block and stale `give_up` reference
…xamples

Reorganize for StateChart users (SCXML-compliant by default):
- Open with practical question, ref behaviour.md for configuration
- Promote block-level catching as first concept (prerequisite)
- Consolidate naming convention to one example (remove near-duplicate)
- Add inline doctest for cleanup/finalize pattern (success + failure)
- Add section on validators not triggering error events
- Remove "Two models" / "When to use which" (redundant with behaviour.md)
- Add seealso to intro for consistency with other pages
- Link StateChart and StateMachine to API definitions
- Clarify backward compat is relative to pre-3.0
- Add inline doctests for atomic_configuration_update showing both modes
- Add cross-references: conditions, transitions, validators, DI
- Fix error_on_execution description: validators are not affected
- Shorten gradual migration section
Reorganize async.md for clarity:
- Open with key insight: API is the same, engine switches automatically
- Promote initial state activation as first gotcha after basic example
- Simplify engine selection table (4 columns, no definition list)
- Clarify concurrent event sending is async-engine exclusive
- Remove redundant sections (versionadded 2.3.0, "StateChart async
  support", duplicate "Asynchronous Support" heading)

Move async from Advanced to Engine in index.md — it's about how the
engine processes callbacks, not an advanced feature.
- Compact installation section (24 lines → 6)
- Separate DPI adjustment as natural follow-up step
- Promote state highlighting to its own subsection
- Fix broken {hint} block that swallowed the code fence
- Move _graph() doctest out of tip to fix doctest parsing
- Rename "Don't want to install Graphviz" to "Online generation"
- Add seealso contextual block for consistency
- Remove versionadded 3.0.0 (noise for v3 release)
- Remove testsetup block, move imports into first doctest
- Remove "Installation" section (was just imports)
- Fix stale {ref}`guards` and {ref}`validators-and-guards` → `conditions`
- Create dedicated "Releases" toctree section in main index
- Move upgrade_2x_to_3 from releases/index to main Releases section
- Add seealso link to upgrade guide at top of 3.0.0 release notes
- Reorganize features into logical groups: Statecharts, Invoke, Event
  dispatch, Error handling, New API, Developer experience
- Move compound/parallel states before Invoke (conceptual dependency)
- Group delayed events, raise_(), cancel_event(), send() params under
  Event dispatch section
- Add missing features: constructor kwargs forwarding, self-transition
  entry/exit behavior, validation flags, In(state) with parallel example
- Replace broken Bugfixes/Misc placeholders removal
- Compact backward-incompatible changes into summary list with link to
  upgrade guide (avoids duplication)
- Fix typos: Dinamically, versios, exiting, recomend, usefull
- Convert non-testable delayed event examples to plain python blocks
  (sync engine blocks on delay)
- Add missing cross-reference links to docs pages
- Add blocking delay note to statechart.md delayed events section

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add AI coding assistant prompt suggestion for automated migration
- Reorder sections to match the quick checklist sequence
- Add cross-reference links to docs pages in every section
- Expand checklist with missing items (is_terminated, self-transitions,
  __repr__, new exports)
- Add Before/After examples to all sections (StateChart vs StateMachine,
  New public exports)
- Clarify StateChart recommendation: about SCXML defaults, not features
- Note current_state.final still works for flat machines
- Recommend class-level listener declarations for new code
- Explain SCXML rationale for discarding unmatched events
- Add tip about error-as-events migration path
- Show concrete trap state example in strict_states Before block
- Condense "New features overview" to single paragraph with link

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove redundant intro paragraph
- Add seealso linking to upgrade guide
- Add Python compatibility notes per series (3.x: 3.9+, 2.x: last
  with 3.7/3.8, 1.x: last with Python 2.x)
- Standardize section heading levels and format

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace the bare toctree index with the full README content via
{include}, giving the docs site a rich landing page with code examples
(flat, guards, compound, parallel, history, eventless, error handling,
async), feature highlights, and installation instructions.

- Remove docs/readme.md (redundant wrapper)
- Hide toctrees so sidebar stays clean
- Remove "Indices and tables" section

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@sonarqubecloud
Copy link

@fgmacedo fgmacedo merged commit 2d7a551 into develop Feb 24, 2026
12 checks passed
@fgmacedo fgmacedo deleted the docs/v3-rewrite branch February 24, 2026 00:23
@codecov
Copy link

codecov bot commented Feb 24, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.95%. Comparing base (300cb34) to head (49253dd).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files
@@             Coverage Diff             @@
##           develop     #582      +/-   ##
===========================================
- Coverage   100.00%   99.95%   -0.05%     
===========================================
  Files           33       33              
  Lines         4145     4145              
  Branches       662      662              
===========================================
- Hits          4145     4143       -2     
- Misses           0        1       +1     
- Partials         0        1       +1     
Flag Coverage Δ
unittests 99.95% <100.00%> (-0.05%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant