Skip to content

Commit 39f6165

Browse files
sergeysalatasergeysalata
committed
added MkDocs
1 parent 354eefd commit 39f6165

8 files changed

Lines changed: 149 additions & 5 deletions

File tree

‎CMakePresets.json‎

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
{
22
"version": 3,
33
"cmakeMinimumRequired": {
4-
"major": 3, "minor": 20, "patch": 0
4+
"major": 3,
5+
"minor": 20,
6+
"patch": 0
57
},
68
"configurePresets": [
79
{
810
"name": "dev",
9-
"displayName": "Dev (Release)",
11+
"displayName": "Dev (Release, Linux)",
1012
"generator": "Unix Makefiles",
1113
"binaryDir": "build",
1214
"cacheVariables": {
@@ -16,18 +18,54 @@
1618
},
1719
{
1820
"name": "dev-debug",
19-
"displayName": "Dev (Debug)",
21+
"displayName": "Dev (Debug, Linux)",
2022
"generator": "Unix Makefiles",
2123
"binaryDir": "build-debug",
2224
"cacheVariables": {
2325
"CMAKE_BUILD_TYPE": "Debug",
2426
"QBIN_BUILD_TESTS": "ON"
2527
}
28+
},
29+
{
30+
"name": "win-msvc",
31+
"displayName": "Windows MSVC (Release)",
32+
"generator": "Visual Studio 17 2022",
33+
"architecture": "x64",
34+
"binaryDir": "build-win",
35+
"cacheVariables": {
36+
"CMAKE_BUILD_TYPE": "Release",
37+
"QBIN_BUILD_TESTS": "ON"
38+
}
39+
},
40+
{
41+
"name": "win-msvc-debug",
42+
"displayName": "Windows MSVC (Debug)",
43+
"generator": "Visual Studio 17 2022",
44+
"architecture": "x64",
45+
"binaryDir": "build-win-debug",
46+
"cacheVariables": {
47+
"CMAKE_BUILD_TYPE": "Debug",
48+
"QBIN_BUILD_TESTS": "ON"
49+
}
2650
}
2751
],
2852
"buildPresets": [
29-
{ "name": "dev", "configurePreset": "dev" },
30-
{ "name": "dev-debug", "configurePreset": "dev-debug" }
53+
{
54+
"name": "dev",
55+
"configurePreset": "dev"
56+
},
57+
{
58+
"name": "dev-debug",
59+
"configurePreset": "dev-debug"
60+
},
61+
{
62+
"name": "win-msvc",
63+
"configurePreset": "win-msvc"
64+
},
65+
{
66+
"name": "win-msvc-debug",
67+
"configurePreset": "win-msvc-debug"
68+
}
3169
],
3270
"testPresets": [
3371
{
@@ -39,6 +77,16 @@
3977
"name": "dev-debug",
4078
"configurePreset": "dev-debug",
4179
"output": { "outputOnFailure": true }
80+
},
81+
{
82+
"name": "win-msvc",
83+
"configurePreset": "win-msvc",
84+
"output": { "outputOnFailure": true }
85+
},
86+
{
87+
"name": "win-msvc-debug",
88+
"configurePreset": "win-msvc-debug",
89+
"output": { "outputOnFailure": true }
4290
}
4391
]
4492
}

‎docs/cli.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# CLI usage
2+
3+
This project provides two command line tools:
4+
5+
- **qbin-compile**: convert OpenQASM source into QBIN format
6+
- **qbin-decompile**: convert QBIN back into OpenQASM
7+
8+
---
9+
10+
## Compile OpenQASM to QBIN
11+
12+
build/compiler/qbin-compile path/to/input.qasm -o out.qbin
13+
14+
- `input.qasm`: OpenQASM source file
15+
- `-o out.qbin`: output file in QBIN format
16+
17+
---
18+
19+
## Decompile QBIN to OpenQASM
20+
21+
build/decompiler/qbin-decompile out.qbin -o roundtrip.qasm
22+
23+
- `out.qbin`: QBIN file produced earlier
24+
- `-o roundtrip.qasm`: reconstructed OpenQASM source
25+
26+
The decompiler preserves canonical formatting for the supported subset and always ends the file with a blank line. This guarantees exact round-trip comparisons in the test suite.
27+
28+
---
29+
30+
## Notes
31+
32+
- Both tools are generated after building with CMake or running `scripts/bootstrap.sh`.
33+
- Executables live in `build/compiler/` and `build/decompiler/`.

‎docs/index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# qbin - a compact binary format for OpenQASM 3
2+
3+
`qbin` is a minimal, lossless binary encoding for a useful subset of OpenQASM 3.
4+
It focuses on code you actually run on hardware (single-/two-qubit gates, rotations,
5+
measurement, and simple conditionals), so state-init circuits and large templated programs shrink dramatically versus plain text QASM.
6+
7+
## Why qbin?
8+
- Size matters: init/state-prep circuits and large parametrized templates shrink a lot.
9+
- Streaming-friendly: one-pass, sectioned layout.
10+
- Round-trip exactness: supported subset decompiles to identical QASM.
11+
12+
See [Quick start](quickstart.md) and [CLI usage](cli.md) to begin.
13+
14+
Check [architecture](architecture.md) for more info about format.

‎docs/install.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Installation

‎docs/quickstart.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Quick start (Linux/macOS)
2+
3+
Requirements:
4+
- CMake >= 3.16
5+
- C++17 compiler
6+
- Python 3
7+
8+
---
9+
10+
## One command (build + test)
11+
12+
./scripts/bootstrap.sh # Release build
13+
./scripts/bootstrap.sh Debug # Debug build
14+
15+
---
16+
17+
## Manual CMake (alternative)
18+
19+
cmake --preset dev
20+
cmake --build --preset dev
21+
ctest --preset dev --output-on-failure
22+
23+
---
24+
25+
## Artifacts after build
26+
27+
- build/compiler/qbin-compile
28+
- build/decompiler/qbin-decompile
29+

‎docs/troubleshooting.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Troubleshooting
2+
3+
## Git password authentication not supported
4+
Use SSH or a Personal Access Token.
5+
6+
## bootstrap.sh not executable
7+
```bash
8+
bash scripts/bootstrap.sh
9+
chmod +x scripts/bootstrap.sh

‎docs/usage.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Usage

‎mkdocs.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
site_name: QBIN
2+
theme:
3+
name: material
4+
5+
nav:
6+
- Home: index.md
7+
- Installation: install.md
8+
- Usage: usage.md
9+
- Architecture: architecture.md

0 commit comments

Comments
 (0)