Quick Start#

Installation#

Install from source (or from PyPI once published):

pip install sphinx-guidestar

For building documentation locally you will also need the theme:

pip install sphinx-guidestar[docs]

Minimal Sphinx example#

Add the extension to your Sphinx conf.py:
```
extensions = [
    'guidestar',
]
```
Place your wireframe HTML in docs/_static/my-app.html.
Use the directive in any RST file:
```
.. guidestar-demo:: _static/my-app.html
   :steps: #start-btn@1500:click, #panel@1000:toggle-class=open, #save-btn@2000:click
   :height: 400px
```
This will:
- Fetch my-app.html at page load
- Inject it into a container with play/pause/restart controls
- Step through the actions, highlighting each target element
- Pause if the user clicks anywhere inside the demo

To show a static snapshot instead — no controls, just the wireframe frozen at a specific state — omit :steps: and use :init-steps-json: to set up the scene:
```
.. guidestar-demo:: _static/my-app.html
   :init-steps-json:
      [
        {"target": "#panel", "action": "add-class", "value": "open"},
        {"target": "#action-btn", "action": "add-class", "value": "active",
         "caption": "Click Action to run the pipeline",
         "captionOptions": {"position": "bottom"}}
      ]
   :height: 400px
```
This will:
- Fetch my-app.html and silently apply the init steps (open the panel, activate the button)
- Render the wireframe frozen at that state — no play/pause controls
- Show the cursor resting on #action-btn (the last targeted init step)
- Display the caption as a persistent overlay
Set :cursor: false to hide the cursor if you want a clean screenshot- like embed with no cursor visible.

Minimal standalone HTML example#

No Sphinx needed — just include the JS and CSS files directly:

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="guidestar-controls.css">
</head>
<body>
    <div data-guidestar
         data-guidestar-config='{
           "htmlSrc": "my-app.html",
           "steps": [
             {"target": "#btn", "action": "click", "delay": 1500, "caption": "Click the button"},
             {"target": "#panel", "action": "toggle-class", "value": "open", "delay": 1000, "caption": "Open the panel", "captionOptions": {"position": "bottom"}}
           ]
         }'>
    </div>
    <script src="guidestar-controller.js"></script>
</body>
</html>