Skip to content

Commit ea8e916

Browse files
hassaansaleem28jcjaskula-aws
hassaansaleem28
and
jcjaskula-aws
authored
feat: complete the Braket SDK cheat sheet with verified snippets (#1279)
Signed-off-by: hassaansaleem28 <iamhassaans@gmail.com> Co-authored-by: Jean-Christophe Jaskula <jjaskula@amazon.com> Reviewed by: peterkomar-aws
1 parent 3fb2d0e commit ea8e916

64 files changed

Lines changed: 2361 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/publish-cheat-sheet.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Publish Cheat Sheet
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
# Allows you to run this workflow manually from the Actions tab
9+
workflow_dispatch:
10+
11+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19+
concurrency:
20+
group: "pages"
21+
cancel-in-progress: false
22+
23+
jobs:
24+
build:
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v4
29+
- name: Setup Pages
30+
uses: actions/configure-pages@v5
31+
- name: Build with Jekyll
32+
uses: actions/jekyll-build-pages@v1
33+
with:
34+
source: ./doc/cheat_sheet
35+
destination: ./_site
36+
- name: Compile cheat sheet for genAI
37+
run: |
38+
python3 doc/cheat_sheet/_scripts/generate_genai_cheat_sheet.py
39+
cp doc/genai_cheat_sheet.md _site/genai_cheat_sheet.md
40+
- name: Upload artifact
41+
uses: actions/upload-pages-artifact@v3
42+
43+
deploy:
44+
environment:
45+
name: github-pages
46+
url: ${{ steps.deployment.outputs.page_url }}
47+
runs-on: ubuntu-latest
48+
needs: build
49+
steps:
50+
- name: Deploy to GitHub Pages
51+
id: deployment
52+
uses: actions/deploy-pages@v4

‎.github/workflows/validate-cheat-sheet.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Validate Cheat Sheet
2+
3+
# Runs on pull requests that touch the cheat sheet. Unlike the publish workflow,
4+
# this only validates -- it never deploys -- so it is safe to run on PRs.
5+
on:
6+
pull_request:
7+
paths:
8+
- "doc/cheat_sheet/**"
9+
- "doc/genai_cheat_sheet.md"
10+
- ".github/workflows/validate-cheat-sheet.yml"
11+
12+
jobs:
13+
verify-snippets:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout
17+
uses: actions/checkout@v4
18+
- name: Set up Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: "3.12"
22+
- name: Install the SDK
23+
run: pip install .
24+
- name: Verify snippets, language parity and GenAI sync
25+
run: python doc/cheat_sheet/_scripts/verify_snippets.py
26+
- name: Check the GenAI cheat sheet is regenerated
27+
run: python doc/cheat_sheet/_scripts/generate_genai_cheat_sheet.py --check

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,11 @@ __pycache__/
3333
.venv/
3434

3535
/doc/examples*.rst
36+
37+
# Jekyll local preview artifacts for the cheat sheet
38+
/doc/cheat_sheet/_site/
39+
/doc/cheat_sheet/.jekyll-cache/
40+
/doc/cheat_sheet/.jekyll-metadata
41+
/doc/cheat_sheet/.bundle/
42+
/doc/cheat_sheet/vendor/
43+
/doc/cheat_sheet/Gemfile.lock

‎doc/cheat_sheet/Gemfile‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
source "https://rubygems.org"
2+
3+
# Jekyll builds the static site locally. The deployed site is built by GitHub
4+
# Pages (the publish workflow uses actions/jekyll-build-pages); this Gemfile
5+
# gives contributors a faithful local preview of the same sources.
6+
gem "jekyll", "~> 4.3"
7+
8+
# Ruby 3.0+ dropped webrick from the standard library and `jekyll serve`
9+
# needs it. Without this line the local server fails to start.
10+
gem "webrick", "~> 1.8"

‎doc/cheat_sheet/LICENSE‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
MIT License
2+
3+
Original (Julia cheat sheet) Copyright (c) 2015 Ian Hellström
4+
Original (Julia cheat sheet) Copyright (c) 2016 Harris Brakmic
5+
Modifications (Braket cheat sheet) Copyright 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
6+
7+
Permission is hereby granted, free of charge, to any person obtaining a copy
8+
of this software and associated documentation files (the "Software"), to deal
9+
in the Software without restriction, including without limitation the rights
10+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
11+
copies of the Software, and to permit persons to whom the Software is
12+
furnished to do so, subject to the following conditions:
13+
14+
The above copyright notice and this permission notice shall be included in all
15+
copies or substantial portions of the Software.
16+
17+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23+
SOFTWARE.

‎doc/cheat_sheet/README.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Amazon Braket SDK Cheat Sheet
2+
3+
A one-page, browsable reference for the most common Amazon Braket SDK calls,
4+
published as a static site to GitHub Pages and mirrored as a single flat
5+
Markdown file for LLM agents.
6+
7+
This directory contains the **source**. The published site is built from it by
8+
the [`publish-cheat-sheet.yml`](../../.github/workflows/publish-cheat-sheet.yml)
9+
workflow on every push to `main`.
10+
11+
## Layout
12+
13+
```
14+
doc/cheat_sheet/
15+
├── _config.yml # Jekyll config + per-language UI strings
16+
├── _data/blocks.yml # the ordered list of sections (the source of truth for order)
17+
├── _includes/
18+
│ ├── blocks.html # renders each section from blocks.yml
19+
│ ├── header.html # the language switcher
20+
│ ├── en/*.md # English sections (one Markdown table per topic)
21+
│ └── fr/*.md # French sections (same code, translated descriptions)
22+
├── _layouts/default.html # page shell
23+
├── _scripts/
24+
│ ├── verify_snippets.py # tests the snippets against the installed SDK
25+
│ └── generate_genai_cheat_sheet.py # builds ../genai_cheat_sheet.md
26+
├── index.html # English entry point
27+
├── index.fr.html # French entry point
28+
└── cheatsheet.css # styling
29+
```
30+
31+
The generated companion file lives at [`../genai_cheat_sheet.md`](../genai_cheat_sheet.md).
32+
33+
## A section is a small Markdown table
34+
35+
Each file in `_includes/en/` is a borderless two-column table, one row per call:
36+
37+
```markdown
38+
| Imports | `from braket.circuits import Circuit` |
39+
| Create a circuit | `circuit = Circuit()` |
40+
```
41+
42+
The left cell is a short description, the right cell is the code (wrap code in
43+
backticks). Use `<br>` to put several lines in one cell.
44+
45+
### Hints for the LLM file
46+
47+
The HTML site hides comments, but the GenAI file keeps them. Use them to add
48+
context that only a machine reader needs:
49+
50+
```markdown
51+
| Create a circuit<!-- LLM: . Note the number of qubits is not a constructor argument--> | `circuit = Circuit()` |
52+
```
53+
54+
The hint text is folded into the description in `genai_cheat_sheet.md`.
55+
56+
## Add or edit a section
57+
58+
1. Edit the relevant file in `_includes/en/` (or create a new `NewTopic.md`).
59+
2. If it is a **new** section, register it in `_data/blocks.yml` at the position
60+
you want it to appear:
61+
```yaml
62+
- file: NewTopic.md
63+
title: New Topic
64+
fr: Nouveau sujet
65+
```
66+
3. Add the matching translation in `_includes/fr/NewTopic.md`. **Keep the code
67+
identical to English** — only translate the descriptions. Every section must
68+
exist in every language or the site build fails.
69+
4. Verify and regenerate (below).
70+
71+
## Verify your changes
72+
73+
The snippets are executable, not decorative. Run the verifier against an
74+
installed copy of the SDK:
75+
76+
```bash
77+
pip install .
78+
python doc/cheat_sheet/_scripts/verify_snippets.py
79+
```
80+
81+
It checks that:
82+
83+
- every `import` in the cheat sheet resolves against the SDK,
84+
- every translated section carries the **same code** as English,
85+
- the GenAI Markdown file is in sync, and
86+
- the local (non-cloud) snippets actually run on `LocalSimulator` and friends.
87+
88+
## Regenerate the GenAI file
89+
90+
After changing any section, rebuild the flat Markdown companion:
91+
92+
```bash
93+
python doc/cheat_sheet/_scripts/generate_genai_cheat_sheet.py
94+
```
95+
96+
Use `--check` to verify it is up to date without writing (this is what CI runs):
97+
98+
```bash
99+
python doc/cheat_sheet/_scripts/generate_genai_cheat_sheet.py --check
100+
```
101+
102+
## Preview the site locally
103+
104+
The site is a standard Jekyll project. The [`Gemfile`](Gemfile) here pins Jekyll
105+
so you get a faithful local preview of the same sources. (The published site is
106+
built by GitHub Pages via the publish workflow, not from this Gemfile.)
107+
108+
### Prerequisites
109+
110+
You need Ruby and Bundler. Check what you have:
111+
112+
```bash
113+
ruby --version # 3.0 or newer is fine
114+
bundler --version # if this fails, run: gem install bundler
115+
```
116+
117+
If you do not have Ruby, follow the Jekyll install guide for your OS:
118+
https://jekyllrb.com/docs/installation/
119+
120+
### Build and serve
121+
122+
From this directory:
123+
124+
```bash
125+
cd doc/cheat_sheet
126+
bundle install # installs Jekyll and its dependencies (first time only)
127+
bundle exec jekyll serve # builds the site and starts a local server
128+
```
129+
130+
Then open http://127.0.0.1:4000 in your browser. The French page is at
131+
http://127.0.0.1:4000/fr/.
132+
133+
> The `Gemfile` includes `webrick` because Ruby 3.0+ no longer ships it in the
134+
> standard library and `jekyll serve` needs it. If you ever see a `webrick`
135+
> `LoadError`, run `bundle install` again.
136+
137+
## Add a new language
138+
139+
See [`Translation.md`](Translation.md) for the end-to-end steps (new `_config.yml`
140+
strings, an `index.TAG.html`, and a translated `_includes/TAG/` folder).
141+
142+
## How it is published
143+
144+
On every push to `main`, the publish workflow builds the Jekyll site, regenerates
145+
`genai_cheat_sheet.md`, and deploys to GitHub Pages. Pull requests do **not**
146+
deploy; instead [`validate-cheat-sheet.yml`](../../.github/workflows/validate-cheat-sheet.yml)
147+
runs the verifier so broken snippets are caught before merge.

‎doc/cheat_sheet/Translation.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Translation Guide
2+
3+
TL;DR:
4+
5+
- See `_config.yml`, `index.fr.html` and `_includes/`
6+
7+
The translation of this cheat-sheet requires the followings steps:
8+
9+
- Choose a tag for your language, such as `en` for English or `fr` for French;
10+
- On [`_config.yml`](_config.yml), add your tag and translate the given phrases;
11+
- Copy `index.html` to `index.TAG.html`, where TAG is your tag;
12+
- Modify `index.TAG.html`, changing `lang: TAG` and `permalink: /TAG/`;
13+
- Copy the folder `_includes/en/` to `_includes/TAG/`, i.e., create a folder `TAG`
14+
inside `_includes` with a copy of all the `.md` files; **don't change the .md names**;
15+
- On file `_data/blocks.yml`, add a ` TAG: translated title` line for each title;
16+
- Translate each block in `_includes/TAG`.
17+

‎doc/cheat_sheet/_config.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
domain: amazon-braket.github.io
2+
title: The Fast Track to Amazon Braket
3+
description: "The Fast Track to Amazon Braket - Braket Cheat Sheet"
4+
github_username: amazon-braket
5+
markdown: kramdown
6+
7+
t:
8+
en:
9+
name: "English"
10+
fast-track: "The Fast Track to Amazon Braket"
11+
github-1: "This page's source is"
12+
github-2: "located here"
13+
github-3: "Pull requests are welcome!"
14+
github-4: "This cheat sheet is inspired by"
15+
translate: "Help translate!" # Not used for `en`
16+
fr:
17+
name: "Français"
18+
fast-track: "Aide-mémoire"
19+
github-1: "Les sources de cette page sont"
20+
github-2: "disponibles ici"
21+
github-3: "Pull Requests bienvenues !"
22+
github-4: "Cet aide-memoire est inspiré de"
23+
translate: "Aidez à traduire !" # Not used for `en`

‎doc/cheat_sheet/_data/blocks.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
- file: What-is.md
2+
title: What is…?
3+
fr: De quoi s'agit-il ?
4+
- file: Circuits.md
5+
title: Circuits
6+
fr: Circuits
7+
- file: FreeParameters.md
8+
title: FreeParameters
9+
fr: Paramètres libres
10+
- file: Tasks.md
11+
title: Tasks
12+
fr: Tâches
13+
- file: ProgramSets.md
14+
title: Program Sets
15+
fr: Ensembles de programmes
16+
- file: Results.md
17+
title: Results
18+
- file: Device.md
19+
title: Device
20+
- file: Reservations.md
21+
title: Reservations
22+
fr: Réservations
23+
- file: DeviceProperties.md
24+
title: Device Properties
25+
- file: ExperimentalCapabilities.md
26+
title: Experimental Capabilities
27+
fr: Fonctionnalités expérimentales
28+
- file: Pricing.md
29+
title: Pricing
30+
- file: HybridJobs.md
31+
title: Hybrid Jobs
32+
fr: Tâches hybrides
33+
- file: Simulators.md
34+
title: Simulators
35+
- file: Emulators.md
36+
title: Emulators
37+
fr: Émulateurs
38+
- file: NoiseSimulation.md
39+
title: Noise Simulation
40+
- file: LLDC.md
41+
title: Low-Level Device Control
42+
- file: AHS.md
43+
title: Analog Hamiltonian Simulation
44+
- file: ErrorMitigation.md
45+
title: Error Mitigation
46+
- file: Console.md
47+
title: Console
48+
- file: APICalls.md
49+
title: API Calls
50+
- file: QiskitProvider.md
51+
title: Qiskit Provider
52+
- file: Resources.md
53+
title: Resources

‎doc/cheat_sheet/_includes/blocks.html‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<div id="contents">
2+
<ul>
3+
<li>
4+
{% for block in site.data.blocks %}
5+
<div class="box">
6+
<div class="title">
7+
8+
{% if page.lang == "en" %}
9+
<h1>{{ block.title }}</h1>
10+
{% elsif block[page.lang] %}
11+
<h1>{{ block[page.lang] }}</h1>
12+
{% else %}
13+
<h1>{{ block.title }} <small>({{ site.t[page.lang].translate }})</small> </h1>
14+
{% endif %}
15+
</div>
16+
{% capture this_block %}{% include {{page.lang}}/{{ block.file }} %}{% endcapture %}
17+
{{ this_block | markdownify }}
18+
</div>
19+
{% endfor %}
20+
</li>
21+
</ul>
22+
</div>

0 commit comments

Comments
 (0)