Merge pull request #2 from OpenQuantumDesign/documentation

Documentation

Author: yhteoh

.github/workflows/check_mkdocs_build.yml

@@ -0,0 +1,37 @@
+name: Check Mkdocs Build
+
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  check_mkdocs_build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Configure Git credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Retrieve Git submodules
+        run: git submodule update --init --recursive && git submodule update --recursive --remote
+
+      - name: Copy examples into docs folder
+        run: cp -r examples/ docs/examples/
+
+      - name: Install repo
+        run: uv sync --extra docs
+
+      - name: Build docs
+        run: uv run mkdocs build

.github/workflows/deploy_docs.yaml

@@ -1,33 +1,37 @@
-name: ci
+name: Deploy Mkdocs Documentation
+
 on:
   push:
-    branches:
-      - master
-      - main
+    branches: ["main"]
+
 permissions:
   contents: write
 
 jobs:
-  deploy:
+  deploy_docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
       - name: Configure Git Credentials
         run: |
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v4
+
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
         with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-      - run: git submodule update --init --recursive
-      - run: git submodule update --recursive --remote
-      - run: cp -r examples/ docs/examples/
-      - run: pip install .[docs]
-      - run: mkdocs gh-deploy --force
+          enable-cache: true
+
+      - name: Retrieve Git submodules
+        run: git submodule update --init --recursive && git submodule update --recursive --remote
+
+      - name: Copy examples into docs folder
+        run: cp -r examples/ docs/examples/
+
+      - name: Install repo
+        run: uv sync --extra docs
+
+      - name: Build docs
+        run: uv run mkdocs gh-deploy --force

.gitignore

@@ -177,3 +177,4 @@ _scripts/
 docs/examples/
 tests/test.bat
 *.zip
+.pre-commit-config.yaml

CODE_OF_CONDUCT.md

@@ -129,4 +129,4 @@ at [https://www.contributor-covenant.org/translations][translations].
 [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
 [Mozilla CoC]: https://github.com/mozilla/diversity
 [FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations
+[translations]: https://www.contributor-covenant.org/translations

README.md

@@ -31,7 +31,7 @@ classical emulation backends, compiler infrastructure, and cloud server containe
 ## Quick start <a name="quickstart"></a>
 
 ## Installation <a name="installation"></a>
-To install `equilux` and the suite Open Quantum Design software tools,  
+To install `equilux` and the suite Open Quantum Design software tools,
 ```bash
 pip install equilux
 ```
@@ -49,47 +49,47 @@ Open Quantum Design's quantum computing stack can be interfaced at different lev
 ```mermaid
 block-beta
    columns 3
-   
+
    block:Interface
        columns 1
        InterfaceTitle("<i><b>Interfaces</b><i/>")
-       InterfaceDigital["<b>Digital Interface</b>\nQuantum circuits with discrete gates"] 
+       InterfaceDigital["<b>Digital Interface</b>\nQuantum circuits with discrete gates"]
        space
-       InterfaceAnalog["<b>Analog Interface</b>\n Continuous-time evolution with Hamiltonians"] 
+       InterfaceAnalog["<b>Analog Interface</b>\n Continuous-time evolution with Hamiltonians"]
        space
        InterfaceAtomic["<b>Atomic Interface</b>\nLight-matter interactions between lasers and ions"]
        space
     end
-    
+
     block:IR
        columns 1
        IRTitle("<i><b>IRs</b><i/>")
-       IRDigital["Quantum circuit IR\nopenQASM, LLVM+QIR"] 
+       IRDigital["Quantum circuit IR\nopenQASM, LLVM+QIR"]
        space
        IRAnalog["openQSIM"]
        space
        IRAtomic["openAPL"]
        space
     end
-    
+
     block:Emulator
        columns 1
        EmulatorsTitle("<i><b>Classical Emulators</b><i/>")
-       
-       EmulatorDigital["Pennylane, Qiskit"] 
+
+       EmulatorDigital["Pennylane, Qiskit"]
        space
        EmulatorAnalog["QuTiP, QuantumOptics.jl"]
        space
        EmulatorAtomic["TrICal, QuantumIon.jl"]
        space
     end
-    
+
     space
     block:RealTime
        columns 1
        RealTimeTitle("<i><b>Real-Time</b><i/>")
        space
-       RTSoftware["ARTIQ, DAX, OQDAX"] 
+       RTSoftware["ARTIQ, DAX, OQDAX"]
        space
        RTGateware["Sinara Real-Time Control"]
        space
@@ -99,32 +99,32 @@ block-beta
        space
     end
     space
-    
+
    InterfaceDigital --> IRDigital
    InterfaceAnalog --> IRAnalog
    InterfaceAtomic --> IRAtomic
-   
+
    IRDigital --> IRAnalog
    IRAnalog --> IRAtomic
-   
+
    IRDigital --> EmulatorDigital
    IRAnalog --> EmulatorAnalog
    IRAtomic --> EmulatorAtomic
-   
+
    IRAtomic --> RealTimeTitle
-   
+
    RTSoftware --> RTGateware
    RTGateware --> RTHardware
    RTHardware --> RTApparatus
-   
+
     classDef title fill:#d6d4d4,stroke:#333,color:#333;
     classDef digital fill:#E7E08B,stroke:#333,color:#333;
     classDef analog fill:#E4E9B2,stroke:#333,color:#333;
     classDef atomic fill:#D2E4C4,stroke:#333,color:#333;
     classDef realtime fill:#B5CBB7,stroke:#333,color:#333;
 
     classDef highlight fill:#f2bbbb,stroke:#333,color:#333,stroke-dasharray: 5 5;
-    
+
     class InterfaceTitle,IRTitle,EmulatorsTitle,RealTimeTitle title
     class InterfaceDigital,IRDigital,EmulatorDigital digital
     class InterfaceAnalog,IRAnalog,EmulatorAnalog analog
@@ -133,19 +133,19 @@ block-beta
 ```
 
 ### Software <a name="software"></a>
-OQD's software stack components include Python interfaces at the digital, analog, and atomic layers, 
-classical emulators, compiler infrastructure, and cloud server components. 
+OQD's software stack components include Python interfaces at the digital, analog, and atomic layers,
+classical emulators, compiler infrastructure, and cloud server components.
 
 ### Hardware <a name="hardware"></a>
 
-Planned supported hardware backends include 
+Planned supported hardware backends include
 the [Bloodstone](docs/hardware/devices.md) processor based on<sup>171</sup>Yb<sup>+</sup> ions
 and the [Beryl](docs/hardware/devices.md) processor based on<sup>133</sup>Ba<sup>+</sup> ions.
 
 
 
 ## Getting started <a name="Getting Started"></a>
-Below is a short example of how to use the analog interface to specify, serialize, 
+Below is a short example of how to use the analog interface to specify, serialize,
 and simulate an analog quantum program - here, a single-qubit Rabi-flopping experiment.
 
 ```python

docs/about.md

@@ -1,20 +1,20 @@
 
 
-Open Quantum Design (OQD) is a non-profit organization. Our mission is to develop full-stack open-source quantum computer designs by fostering a collaborative community of diverse contributors from academia, industry, and government. 
-OQD's current designs are based on laser-cooled trapped ion quantum computing hardware and software. 
+Open Quantum Design (OQD) is a non-profit organization. Our mission is to develop full-stack open-source quantum computer designs by fostering a collaborative community of diverse contributors from academia, industry, and government.
+OQD's current designs are based on laser-cooled trapped ion quantum computing hardware and software.
 The OQD intellectual property was developed by University of Waterloo Professors Crystal Senko, Rajibul Islam and Roger Melko, with physicists, engineers, and computer scientists working at the [Institute for Quantum Computing](https://uwaterloo.ca/institute-for-quantum-computing/) and the [Perimeter Institute Quantum Intelligence Lab](https://perimeterinstitute.ca/perimeter-institute-quantum-intelligence-lab-piquil).
 
 OQD’s technology features novel and scalable approaches for the trapping, control, and read-out of ions. This includes a unique blade trap design, agile optical scheme for low crosstalk addressing of the ions, high-fidelity and all-to-all gate connectivity, and native support for mid-circuit measurements.
 
-All components of the stack will be open under an Apache 2.0 or similar license - from hardware designs and the middleware control stack, to the top level programming interfaces. OQD’s vision is to be a global leader in open quantum technology, driving breakthroughs that revolutionize science, industry, and society, in order to improve the quality of life for future generations. 
+All components of the stack will be open under an Apache 2.0 or similar license - from hardware designs and the middleware control stack, to the top level programming interfaces. OQD’s vision is to be a global leader in open quantum technology, driving breakthroughs that revolutionize science, industry, and society, in order to improve the quality of life for future generations.
 
 ## Why Open?
 
 Open-source is more accessible and a proven environment for innovation. By sharing resources, knowledge, and designs, a global community of participants from diverse backgrounds can contribute to and accelerate the development of quantum technologies. OQD is building a collaborative community for technology co-creation, in order to democratize and accelerate the benefits of quantum computing technologies for all. Our purpose is to harness the potential of open quantum technology for the betterment of society, ensuring equitable access to its benefits, to foster an environment for innovation, and nurture the quantum workforce of the future.
 
 
 ## OQD’s open-source approach:
- 
+
 * Provides transparency and accessibility to software and hardware
 * Deepens connections between academia, industry, and government through a collaborative sandbox with clear rules of engagement
 * Builds trust through collective decision-making to the benefit of the ecosystem and technology

docs/get-started.md

@@ -1,5 +1,5 @@
-## Installation 
-To install, 
+## Installation
+To install,
 ```bash
 pip install git+https://github.com/OpenQuantumDesign/equilux.git
 ```
@@ -11,7 +11,7 @@ git clone https://github.com/OpenQuantumDesign/equilux
 pip install .
 ```
 
-## Documentation 
+## Documentation
 
 Documentation is implemented with [MkDocs](https://www.mkdocs.org/) and can be read from the [docs](https://github.com/OpenQuantumDesign/midstack/tree/main/docs) folder.
 
@@ -26,4 +26,4 @@ To deploy the documentation server locally:
 ```
 cp -r examples/ docs/examples/
 mkdocs serve
-```
+```

docs/hardware/devices.md

@@ -16,57 +16,57 @@ This documentation is still under development, we welcome contributions! © Open
 
 ## What's Here
 The heart of Open Quantum Design's mission and vision is to build open-source, full-stack
-quantum computers. The second generation of trapped-ion devices, coined [Bloodstone](#bloodstone) and [Beryl](#beryl), 
+quantum computers. The second generation of trapped-ion devices, coined [Bloodstone](#bloodstone) and [Beryl](#beryl),
 are currently under construction and testing. Designs, including electrical, photonic, and mechanical,
-will be opened sourced for community use and contribution. 
+will be opened sourced for community use and contribution.
 The real-time control stack builds on top of the open-hardware [Sinara](#sinara) ecosystem,
 including [ARTIQ](#artiq) and [DAX](#dax)
 
 
 ```mermaid
 block-beta
    columns 3
-   
+
    block:Interface
        columns 1
        InterfaceTitle("<i><b>Interfaces</b><i/>")
-       InterfaceDigital["<b>Digital Interface</b>\nQuantum circuits with discrete gates"] 
+       InterfaceDigital["<b>Digital Interface</b>\nQuantum circuits with discrete gates"]
        space
-       InterfaceAnalog["<b>Analog Interface</b>\n Continuous-time evolution with Hamiltonians"] 
+       InterfaceAnalog["<b>Analog Interface</b>\n Continuous-time evolution with Hamiltonians"]
        space
        InterfaceAtomic["<b>Atomic Interface</b>\nLight-matter interactions between lasers and ions"]
        space
     end
-    
+
     block:IR
        columns 1
        IRTitle("<i><b>IRs</b><i/>")
-       IRDigital["Quantum circuit IR\nopenQASM, LLVM+QIR"] 
+       IRDigital["Quantum circuit IR\nopenQASM, LLVM+QIR"]
        space
        IRAnalog["openQSIM"]
        space
        IRAtomic["openAPL"]
        space
     end
-    
+
     block:Emulator
        columns 1
        EmulatorsTitle("<i><b>Classical Emulators</b><i/>")
-       
-       EmulatorDigital["Pennylane, Qiskit"] 
+
+       EmulatorDigital["Pennylane, Qiskit"]
        space
        EmulatorAnalog["QuTiP, QuantumOptics.jl"]
        space
        EmulatorAtomic["TrICal, QuantumIon.jl"]
        space
     end
-    
+
     space
     block:RealTime
        columns 1
        RealTimeTitle("<i><b>Real-Time</b><i/>")
        space
-       RTSoftware["ARTIQ, DAX, OQDAX"] 
+       RTSoftware["ARTIQ, DAX, OQDAX"]
        space
        RTGateware["Sinara Real-Time Control"]
        space
@@ -76,24 +76,24 @@ block-beta
        space
     end
     space
-    
+
    InterfaceDigital --> IRDigital
    InterfaceAnalog --> IRAnalog
    InterfaceAtomic --> IRAtomic
-   
+
    IRDigital --> IRAnalog
    IRAnalog --> IRAtomic
-   
+
    IRDigital --> EmulatorDigital
    IRAnalog --> EmulatorAnalog
    IRAtomic --> EmulatorAtomic
-   
+
    IRAtomic --> RealTimeTitle
-   
+
    RTSoftware --> RTGateware
    RTGateware --> RTHardware
    RTHardware --> RTApparatus
-   
+
    classDef title fill:#d6d4d4,stroke:#333,color:#333;
    classDef digital fill:#E7E08B,stroke:#333,color:#333;
    classDef analog fill:#E4E9B2,stroke:#333,color:#333;
@@ -107,7 +107,7 @@ block-beta
     class InterfaceAnalog,IRAnalog,EmulatorAnalog analog
     class InterfaceAtomic,IRAtomic,EmulatorAtomic atomic
     class RTSoftware,RTGateware,RTHardware,RTApparatus realtime
-    
+
     class RealTime highlight
 ```