Skip to content

Commit a7dc38d

Browse files
weinbe58weinbe58
committed
backport #20 
1 parent 5a72e35 commit a7dc38d

File tree

13 files changed

+630
-3
lines changed

13 files changed

+630
-3
lines changed

‎.github/workflows/devdoc.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Deploy Devopment Branch Docs
2+
on:
3+
push:
4+
branches:
5+
- main
6+
7+
concurrency:
8+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
9+
cancel-in-progress: true
10+
11+
jobs:
12+
documentation:
13+
name: Deploy dev documentation
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
with:
18+
fetch-depth: 0
19+
- name: Install uv
20+
uses: astral-sh/setup-uv@v6
21+
with:
22+
# Install a specific version of uv.
23+
version: "0.5.1"
24+
enable-cache: true
25+
cache-dependency-glob: "uv.lock"
26+
- name: Install Documentation dependencies
27+
run: uv sync --group doc --index="https://${{ secrets.JFROG_USER}}:${{ secrets.JFROG_TOKEN }}@quera.jfrog.io/artifactory/api/pypi/quera-pypi-algo/simple/"
28+
- name: Set up build cache
29+
uses: actions/cache@v4
30+
id: cache
31+
with:
32+
key: mkdocs-material-${{ github.ref }}
33+
path: .cache
34+
restore-keys: |
35+
mkdocs-material-
36+
# derived from:
37+
# https://github.com/RemoteCloud/public-documentation/blob/dev/.github/workflows/build_docs.yml
38+
- name: Configure Git user
39+
run: |
40+
git config --local user.email "github-actions[bot]@users.noreply.github.com"
41+
git config --local user.name "github-actions[bot]"
42+
- name: Deploy documentation
43+
env:
44+
GH_TOKEN: ${{ secrets.GH_TOKEN }}
45+
GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
46+
run: |
47+
git fetch origin gh-pages --depth=1
48+
uv run mike deploy -p dev

‎.github/workflows/doc.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Documentation (preview)
2+
on:
3+
pull_request:
4+
types:
5+
- opened
6+
- reopened
7+
- synchronize
8+
- closed
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
documentation:
15+
name: Deploy preview documentation
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/checkout@v4
19+
- name: Install uv
20+
uses: astral-sh/setup-uv@v6
21+
with:
22+
# Install a specific version of uv.
23+
version: "0.5.1"
24+
enable-cache: true
25+
cache-dependency-glob: "uv.lock"
26+
- name: Install Documentation dependencies
27+
run: uv sync --group doc --index="https://${{ secrets.JFROG_USER}}:${{ secrets.JFROG_TOKEN }}@quera.jfrog.io/artifactory/api/pypi/quera-pypi-algo/simple/"
28+
- name: Set up build cache
29+
uses: actions/cache@v4
30+
id: cache
31+
with:
32+
key: mkdocs-material-${{ github.ref }}
33+
path: .cache
34+
restore-keys: |
35+
mkdocs-material-
36+
- name: Deploy documentation
37+
env:
38+
GH_TOKEN: ${{ secrets.GH_TOKEN }}
39+
run: |
40+
uv run mkdocs build
41+
- name: Deploy preview
42+
uses: rossjrw/pr-preview-action@v1
43+
with:
44+
source-dir: ./site

‎.github/workflows/pub_doc.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Deploy Release Docs
2+
on:
3+
push:
4+
tags:
5+
- "v*"
6+
7+
concurrency:
8+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
9+
cancel-in-progress: true
10+
11+
jobs:
12+
documentation:
13+
name: Deploy release documentation
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
with:
18+
fetch-depth: 0
19+
- name: Install uv
20+
uses: astral-sh/setup-uv@v6
21+
with:
22+
# Install a specific version of uv.
23+
version: "0.5.1"
24+
enable-cache: true
25+
cache-dependency-glob: "uv.lock"
26+
- name: Install Documentation dependencies
27+
run: uv sync --group doc --index="https://${{ secrets.JFROG_USER}}:${{ secrets.JFROG_TOKEN }}@quera.jfrog.io/artifactory/api/pypi/quera-pypi-algo/simple/"
28+
- name: Set up build cache
29+
uses: actions/cache@v4
30+
id: cache
31+
with:
32+
key: mkdocs-material-${{ github.ref }}
33+
path: .cache
34+
restore-keys: |
35+
mkdocs-material-
36+
# derived from:
37+
# https://github.com/RemoteCloud/public-documentation/blob/dev/.github/workflows/build_docs.yml
38+
- name: Configure Git user
39+
run: |
40+
git config --local user.email "github-actions[bot]@users.noreply.github.com"
41+
git config --local user.name "github-actions[bot]"
42+
- name: Set release notes tag
43+
run: |
44+
export TAG_PATH=${{ github.ref }}
45+
echo ${TAG_PATH}
46+
echo "TAG_VERSION=${TAG_PATH##*/}" >> $GITHUB_ENV
47+
echo ${TAG_VERSION}
48+
- name: Deploy documentation
49+
env:
50+
GH_TOKEN: ${{ secrets.GH_TOKEN }}
51+
run: |
52+
git fetch origin gh-pages --depth=1
53+
uv run mike deploy --update-alias --push ${TAG_VERSION} latest

‎README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Welcome to Bloqade-Geometry
2+
<!--- TODO: fix links after making repo public --->
3+
Bloqade-Geometry is a collection of tools for transforming and modeling geometric
4+
objects used for defining layouts and operation of neutral atom quantum computers.
5+
6+
Currently the only supported geometry is a grid, but more geometries will be added in
7+
the future. For a full list of features, see the [API Reference](reference/bloqade/geometry/prelude/).
8+
9+
[API Reference](reference/bloqade/geometry/prelude/).
10+
11+
## Installation
12+
13+
```bash
14+
uv add bloqade-geometry
15+
```
16+
17+
See [Installation](install.md) for more details.

‎docs/contrib.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Contributing
2+
3+
Please see [Installation](install.md) for instructions on how to set up your
4+
development environment.
5+
6+
## Pre-commit hooks
7+
8+
We use `pre-commit` to run the linter checks before you commit your changes. The
9+
pre-commit hooks are installed as part of the development dependencies. You can
10+
setup `pre-commit` using the following command:
11+
12+
```bash
13+
pre-commit install
14+
```
15+
16+
This will run the linter checks before you commit your changes. If the checks fail,
17+
the commit will be rejected. Most of the following sections can be checked by the
18+
pre-commit hooks.
19+
20+
## Running the tests
21+
22+
We use `pytest` for testing. To run the tests, simply run:
23+
24+
```bash
25+
pytest
26+
```
27+
28+
or for a specific test file with the `-s` flag to show the output of the program:
29+
30+
```bash
31+
pytest -s tests/test_program.py
32+
```
33+
34+
lots of tests contains pretty printing of the IR themselves, so it's useful to see the
35+
output.
36+
37+
## Code style
38+
39+
We use `black` for code formatting. Besides the linter requirements, we also require
40+
the following
41+
good-to-have practices:
42+
43+
### Naming
44+
45+
- try not to use abbreviation as names, unless it's a common abbreviation like `idx`
46+
for `index`
47+
- try not create a lot of duplicated name prefix unless the extra information is
48+
necessary when accessing the class object.
49+
- try to use `snake_case` for naming variables and functions, and `CamelCase`
50+
for classes.
51+
52+
### Comments
53+
54+
- try not to write comments, unless it's really necessary. The code should be
55+
self-explanatory.
56+
- if you have to write comments, try to use `NOTE:`, `TODO:` `FIXME:` tags to make it
57+
easier to search for them.
58+
59+
## Documentation
60+
61+
We use `just` for mangaging command line tools and scripts. It should be installed when
62+
you run `uv sync`. To build the documentation, simply run:
63+
64+
```bash
65+
just doc
66+
```
67+
68+
This will launch a local server to preview the documentation. You can also run
69+
`just doc-build` to build the documentation without launching the server.

‎docs/index.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Welcome to Bloqade-Geometry
2+
3+
Bloqade-Geometry is a collection of tools for transforming and modeling geometric
4+
objects used for defining layouts and operation of neutral atom quantum computers.
5+
6+
Currently the only supported geometry is a grid, but more geometries will be added in
7+
the future. For a full list of features, see the [API Reference](reference/bloqade/geometry/prelude/).
8+
9+
## Installation
10+
11+
```bash
12+
uv add bloqade-geometry
13+
```
14+
15+
See [Installation](install.md) for more details.

‎docs/install.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Installation
2+
3+
Bloqade Geometry is available on the PyPI registry. Bloqade Geometry supports Python
4+
3.10 or later. We recommend using Python 3.10+ for the best experience.
5+
6+
We strongly recommend developing project using [`uv`](https://docs.astral.sh/uv/),
7+
which is the official development environment for Kirin and Bloqade Geometry. You can
8+
install `uv` using the following command:
9+
10+
=== "Linux and macOS"
11+
12+
```bash
13+
curl -LsSf https://astral.sh/uv/install.sh | sh
14+
```
15+
16+
17+
=== "Windows"
18+
19+
```cmd
20+
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
21+
```
22+
23+
## Install package:
24+
```bash
25+
uv add bloqade-geometry
26+
```
27+
28+
## Development
29+
30+
We use `uv` to manage the development environment, after you install `uv`, you can
31+
install the development dependencies using the following command:
32+
33+
```bash
34+
uv sync
35+
```
36+
37+
Our code review requires that you pass the tests and the linting checks. We recommend
38+
you to install `pre-commit` to run the checks before you commit your changes, the command line
39+
tool `pre-commit` has been installed as part of the development dependencies. You can setup
40+
`pre-commit` using the following command:
41+
42+
```bash
43+
pre-commit install
44+
```

‎docs/scripts/gen_ref_nav.py‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# type: ignore
2+
"""Generate the code reference pages and navigation."""
3+
4+
from pathlib import Path
5+
6+
import mkdocs_gen_files
7+
8+
SRC_PATH = "src"
9+
10+
skip_keywords = []
11+
12+
nav = mkdocs_gen_files.Nav()
13+
for path in sorted(Path(SRC_PATH).rglob("*.py")):
14+
module_path = path.relative_to(SRC_PATH).with_suffix("")
15+
doc_path = path.relative_to(SRC_PATH).with_suffix(".md")
16+
full_doc_path = Path("reference", doc_path)
17+
18+
iskip = False
19+
20+
for kwrd in skip_keywords:
21+
if kwrd in str(doc_path):
22+
iskip = True
23+
break
24+
if iskip:
25+
print("[Ignore]", str(doc_path))
26+
continue
27+
28+
print("[>]", str(doc_path))
29+
30+
parts = tuple(module_path.parts)
31+
32+
if parts[-1] == "__init__":
33+
parts = parts[:-1]
34+
doc_path = doc_path.with_name("index.md")
35+
full_doc_path = full_doc_path.with_name("index.md")
36+
37+
# [note] if selectionally ignore some files
38+
# elif parts[-1].startswith("_wrapper"):
39+
# pass
40+
# else:
41+
# continue
42+
43+
nav[parts] = doc_path.as_posix()
44+
with mkdocs_gen_files.open(full_doc_path, "w") as fd:
45+
ident = ".".join(parts)
46+
fd.write(f"::: {ident}")
47+
48+
mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path)
49+
50+
with mkdocs_gen_files.open("reference/SUMMARY.txt", "w") as nav_file:
51+
nav_file.writelines(nav.build_literate_nav())

‎docs/stylesheets/extra.css‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
:root {
2+
--md-primary-fg-color: #1cb5ba;
3+
--md-accent-fg-color: #1cb5ba;
4+
}
5+
6+
7+
#logo_light_mode {
8+
display: var(--md-footer-logo-light-mode);
9+
}
10+
11+
#logo_dark_mode {
12+
display: var(--md-footer-logo-dark-mode);
13+
}
14+
15+
[data-md-color-scheme="slate"] {
16+
--md-footer-logo-dark-mode: block;
17+
--md-footer-logo-light-mode: none;
18+
}
19+
20+
[data-md-color-scheme="default"] {
21+
--md-footer-logo-dark-mode: none;
22+
--md-footer-logo-light-mode: block;
23+
}
24+
25+
/* Example for setting a maximum width for code blocks */
26+
pre code {
27+
max-width: 800px; /* Adjust this value as needed (e.g., 100% for full width) */
28+
overflow-x: auto; /* Adds horizontal scrollbar if content exceeds width */
29+
}
30+
31+
/* Example for adjusting content area width for the Material theme */
32+
.md-grid {
33+
max-width: 1240px; /* Increase the overall content area width */
34+
}

‎justfile‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,9 @@ coverage-unit:
1818
coverage report --include="**/types.py","**/taskgen.py","**/concrete.py"
1919

2020
coverage: coverage-run coverage-xml coverage-report
21+
22+
doc:
23+
mkdocs serve
24+
25+
doc-build:
26+
mkdocs build

0 commit comments

Comments
 (0)