Initial version of docs + HQAR -> QART rename (#5)

* Add docs stub

* Add language server info to mkdocs.yml

* Add basic docs structure

* Add basic program/circuit example

* Add short desription of QART format

* Add API reference

* Update mkdocs.yml

* Remove copyright notices

* Rename hqar package to qart

* Remove copyright checks

* Remove remaining copyright notices

* Reorganize chapter on QART Python library

* Add content to index.md

* Add required plugins

* Reorganize docs for python library

* Remove whitespace

* Update example yaml and svg (my_algorithm -> my_program)

* Add basic development guide

* Update links in index.md

* Add docs-related dependencies

* Add more descriptions to format chapter

* Add job for building docs

* Attempt running mkdocs through poetry run

* Add missing dependency on mkdocstrings

* Apply changes suggested in the review

* Add missing images

.flake8

@@ -25,7 +25,3 @@ ignore =
 per-file-ignores =
     tests/**/test_*.py:D103,D102,D101
     __init__.py:F401
-copyright-check = True
-copyright-regexp = Copyright\s+(©\s+)?\d{4}([-,]\d{4})*\s+%(author)s
-copyright-author = PsiQuantum Corp.
-copyright-min-file-size = 1

.github/workflows/quality_checks.yaml

@@ -40,3 +40,19 @@ jobs:
             pre-commit run -a
       - name: Run mypy
         run: MYPYPATH=src poetry run mypy --install-types --non-interactive src
+
+  test_docs_are_building:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.10"
+      - uses: actions/checkout@v2
+      - name: Setup poetry
+        uses: abatilo/actions-poetry@v2
+      - name: Install package and deps
+        run: |
+            poetry install --with docs
+      - name: Build docs
+        run: poetry run mkdocs build

.pre-commit-config.yaml

@@ -20,4 +20,3 @@ repos:
     rev: 6.0.0
     hooks:
       - id: flake8
-        additional_dependencies: [flake8-copyright]

README.md

@@ -1,30 +1,30 @@
-# HQAR
-Hierarchical Quantum Algorithms Representation is an open format for representing
+# QART
+Quantum Algorithms Represented Topologically (QART) is an open format for representing
 quantum algorithms, optimized for usage in quantum resource estimation (QRE).
 
-HQAR comprises:
+QART comprises:
 
 - Definition of data format, formalized as a JSON schema.
-- A Python library for validation of quantum programs written in HQAR format using [Pydantic](https://docs.pydantic.dev/).
-- Rudimentary visualization tool `hqar-render`.
+- A Python library for validation of quantum programs written in QART format using [Pydantic](https://docs.pydantic.dev/).
+- Rudimentary visualization tool `qart-render`.
 
 ## Installation
 
-Using HQAR data format does not require installation - you can easily write quantum
+Using QART data format does not require installation - you can easily write quantum
 programs in YAML or JSON.
 
-To install HQAR Python package, clone this repository and install it as usual with `pip`:
+To install QART Python package, clone this repository and install it as usual with `pip`:
 
 ```bash
-# Clone HQAR repo (you can use HTTP link as well)
-git clone git@github.com:PsiQ/hqar.git
-cd hqar
+# Clone QART repo (you can use HTTP link as well)
+git clone git@github.com:PsiQ/qart.git
+cd qart
 pip install .
 ```
 
-## HQAR format
+## QART format
 
-HQAR format represents quantum programs as a hierarchical directed acyclic graphs (DAGs).
+QART format represents quantum programs as a hierarchical directed acyclic graphs (DAGs).
 That's a mouthful, so let us unpack what it means:
 
 - *hierarchical*: each node can contain subgraphs, i.e. routines can be nested inside
@@ -36,7 +36,7 @@ Consider the following hierarchical DAG of a hypothetical quantum program:
 
 ![program example](example_routine.svg)
 
-It can be succinctly written in HQAR format as:
+It can be succinctly written in QART format as:
 
 
 ```yaml
@@ -103,21 +103,21 @@ program:
 ```
 
 
-For full description of HQAR format, check our [docs](https://example.com).
+For full description of QART format, check our [docs](https://example.com).
 
-## Using HQAR package
+## Using QART package
 
-### Using JSON schema for validating data in HQAR format
+### Using JSON schema for validating data in QART format
 
-JSON schema for HQAR format can be obtained by calling `generate_program_schema` function.
+JSON schema for QART format can be obtained by calling `generate_program_schema` function.
 Such schema can be then used for validating user's input, e.g. using `jsonschema` package:
 
 ```python
 from jsonschema import validate
-from hqar import generate_program_schema
+from qart import generate_program_schema
 
 # Hypothetical function loading your data as native Python dictionary.
-data = load_some_program()  
+data = load_some_program()
 schema = generate_program_schema()
 
 # This will raise if there are some validation errors.
@@ -126,12 +126,12 @@ validate(schema, data)
 
 ### Validation using Pydantic models
 
-If you are familiar with Pydantic, you might find it easier to work with HQAR Pydantic
+If you are familiar with Pydantic, you might find it easier to work with QART Pydantic
 models instead of interacting with JSON schema directly. In the example below, we create
-an instance of `SchemaV1` model from validated data stored in HQAR format:
+an instance of `SchemaV1` model from validated data stored in QART format:
 
 ```python
-from hqar import SchemaV1
+from qart import SchemaV1
 
 data = load_some_program()
 

docs/development.md

@@ -0,0 +1,37 @@
+# Development guide
+
+## Setting up development environment
+
+QART uses [Poetry](https://python-poetry.org/) for managing dependencies.
+Therefore, we recommend you use Poetry to setup your environment. However,
+if you insist on not using Poetry, the more traditional way of using
+editable install with `pip` is still avaiable.
+
+### Using editable install with Poetry
+
+To setup your development environment install poetry (if you don't have it yet):
+
+```bash
+pip install poetry
+```
+
+And then install the project and its dependencies:
+
+```bash
+poetry install
+```
+
+### Using editable install with pip
+
+You can also develop Poetry using `pip`:
+
+```bash
+pip install -e .
+```
+
+!!! Warning
+
+    If you are planning to add/modify dependencies of QART, we
+    highly recommend you use Poetry instead of pip editable install.
+    Without Poetry, you will need to edit dependencies manually,
+    which is very error-prone.