docs(state_machine): link and embed the HFSM playground - #777
Merged
Conversation
The state machine docs described webgme-hfsm and showed a PNG of the example machine. The playground now runs the whole toolchain in a browser, so the docs can show the machine itself instead: the reader can drag states, run the simulator and read the generated C++ without leaving the page or installing anything. Embedded with the same pattern odrive_ascii.rst already uses for its web console -- an "open in a new tab" link above, then the iframe -- and the PNG stays for the PDF build, where a raw HTML block renders as nothing. The second webgme-hfsm reference is anonymous (`__`) so it does not collide with the named target in the intro; the file parses clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E4hRq1q5VGPjNn2dnkkqBy
Contributor
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Pull request overview
Updates the core state machine documentation to link to and embed the live webgme-hfsm “HFSM Playground” so readers can interact with the example model directly in the docs.
Changes:
- Clarifies where the example HFSM model lives and that it’s generated as part of the example build.
- Adds a new “Modeling and generating a state machine” section with playground links and a live embedded iframe.
- Documents a CLI one-liner for generating C++ from an HFSM model.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| The example runs the generated code for the following example hsfm (which is | ||
| provided and for which the code was generated from webgme-hfsm): | ||
| The example runs the generated code for the following example hsfm, which is | ||
| provided as a model (``components/state_machine/example/main/Complex.json``) |
Comment on lines
+39
to
+42
| <iframe src="https://finger563.github.io/webgme-hfsm/?example=Complex&view=diagram&embed=1" | ||
| title="The Complex example HFSM in the HFSM Playground" | ||
| loading="lazy" | ||
| style="width:100%;height:640px;border:1px solid var(--color-background-border,#ccc);border-radius:8px;margin-top:0.5em"></iframe> |
|
|
||
| .. code-block:: sh | ||
|
|
||
| npx -p webgme-hfsm hfsm-gen my_machine.json -o generated --no-support |
|
|
||
| The example runs the generated code for the following example hsfm (which is | ||
| provided and for which the code was generated from webgme-hfsm): | ||
| The example runs the generated code for the following example hsfm, which is |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion to #776.
The state machine docs described webgme-hfsm and showed a PNG of the example machine. The playground now runs the whole toolchain in a browser, so the docs can show the machine itself — the reader can drag states, run the simulator, and read the generated C++ without leaving the page or installing anything.
doc/en/core/state_machine.rstgains a "Modeling and generating a state machine" section with:The READMEs already get their playground links from #776, and
state_machine_example.mdincludes the example README, so those flow through without touching them here.Details
odrive_ascii.rstalready embeds its web console this way — "open in a new tab" link above, then the iframe with the same border/radius style andvar(--color-background-border,#ccc). I matched it rather than inventing a second convention.raw:: htmlblock renders as nothing in the LaTeX/PDF build, so the static image is still there for readers who get the PDF.webgme-hfsmlink is anonymous (__) so it doesn't collide with the named target in the intro — that would otherwise be a duplicate-target message, and this repo tracks sphinx warnings.Verified
The docs workflow only runs on push to
main, so CI will not check this PR — a broken directive would surface after merge. So I checked it directly:state_machine.rstwith docutils (sphinx/esp-docs directives stubbed): zero messages at INFO and above, onerawblock, both sections found