Initial commit

.dockerignore

@@ -0,0 +1,7 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+*.egg-info
+dist
+build

.github/dependabot.yml

@@ -0,0 +1,17 @@
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore"
+      include: "scope"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/pre-commit-au.yml

@@ -0,0 +1,21 @@
+name: Pre-commit auto-update
+
+on:
+  # every day at midnight
+  schedule:
+    - cron: "0 0 * * *"
+  # on demand
+  workflow_dispatch:
+
+jobs:
+  upgrade:
+    uses: browniebroke/github-actions/.github/workflows/pre-commit-autoupdate.yml@v1
+    secrets:
+      gh_pat: ${{ secrets.GITHUB_TOKEN }}
+    with:
+      # Inputs listed with their default (all optional)
+      config_path: ".pre-commit-config.yaml" # path is relative to repository root
+      python_version: "3.11"
+      branch_name: "update/pre-commit-hooks"
+      pull_request_title: "chore(deps): upgrade pre-commit dependencies"
+      commit_message: "chore(deps): upgrade pre-commit dependencies"

.github/workflows/python-app.yml

@@ -0,0 +1,56 @@
+name: Python application
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  merge_group:
+      types: [checks_requested]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools
+        python -m pip install -r requirements.txt
+        python -m pip install -e .
+    - name: Pre-commit checks
+      run: |
+        python -m pip install pre-commit
+        pre-commit run --all-files
+    - name: Run tests
+      run: |
+        python -m pytest
+    - name: Sphinx documentation build
+      run: |
+        make docs
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+      with:
+        publish_branch: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html/
+        force_orphan: true
+
+    # TODO in the future
+    # - name: Build and push Docker image
+    #   uses: docker/build-push-action@v2
+    #   with:
+    #     context: .
+    #     push: true
+    #     tags: nathfitz/test:latest

.gitignore

@@ -0,0 +1,19 @@
+# qtmlib/.gitignore file contents
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.idea/
+.vscode/
+__pypackages__/
+*.log
+*.swp
+.DS_Store
+.qtmlib/
+*.venv/
+
+# autogenerated by sphinx-napoleon
+docs/source/modules.rst
+docs/source/pytemplate.rst

.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: check-yaml
+      - id: check-added-large-files
+      # Python-specific
+      - id: check-ast
+      - id: check-docstring-first
+      - id: debug-statements
+
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.16.23
+    hooks:
+      - id: typos
+        args: []
+
+  - repo: https://github.com/psf/black
+    rev: 23.11.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.7
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.339
+    hooks:
+      - id: pyright

Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim-buster
+
+# Set the working directory to /pytemplate
+WORKDIR /pytemplate
+
+# Copy the pyproject.toml and requirements.txt files to the container
+COPY . .
+
+# Install the dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Start the web server
+CMD ["python", "-m", "pytemplate.main"]

Makefile

@@ -0,0 +1,23 @@
+.PHONY: install dev tests lint docs clean build
+
+install:
+	pip install .
+
+dev:
+	pip install -e .
+
+tests:
+	pytest .
+
+lint:
+	pre-commit run --all-files
+
+docs:
+	sphinx-apidoc -f -o docs/source/ pytemplate
+	sphinx-build -M html docs/source/ docs/build/
+
+clean:
+	rm -rf *.egg-info dist build docs/build
+
+build: clean
+	python -m build --sdist -n

README.md

@@ -0,0 +1,75 @@
+# pytemplate
+
+This is a Python 3.11 app called pytemplate. The project includes Docker, Pyright, Ruff, GitHub Actions, Black, pre-commit, and Sphinx.
+
+## Project Structure
+
+The project structure is as follows:
+
+```sh
+pytemplate
+├── .dockerignore
+├── .github
+│   └── workflows
+│       └── python-app.yml
+├── .gitignore
+├── .pre-commit-config.yaml
+├── Dockerfile
+├── Makefile
+├── README.md
+├── docs
+│   ├── Makefile
+│   └── source
+│       ├── conf.py
+│       └── index.rst
+├── pyproject.toml
+├── pytemplate
+│   ├── __init__.py
+│   ├── main.py
+│   └── utils.py
+├── requirements.txt
+├── ruff.toml
+└── tests
+    ├── test_main.py
+    └── test_utils.py
+```
+
+The source code is located in the `pytemplate` folder, which contains the `__init__.py`, `main.py`, and `utils.py` files. The tests are located in the `tests` folder, which contains the `test_main.py` and `test_utils.py` files.
+
+The project uses toml for configuration instead of `setup.py`. The configuration file is located in `pyproject.toml`.
+
+The project includes Docker, with a `Dockerfile` located in the root directory. The `.dockerignore` file is also located in the root directory.
+
+The project includes Pyright for static type checking, pre-commit for code formatting, Black for code formatting and Ruff for linting. The configuration for these tools is located in the `.pre-commit-config.yaml` and `ruff.toml` files.
+
+The project includes Sphinx for documentation, with the documentation located in the `docs` folder. The `source/conf.py` file contains the configuration for Sphinx.
+
+The project includes GitHub Actions for continuous integration, with the configuration located in the `.github/workflows/python-app.yml` file.
+
+## Usage Notes
+
+[Replace](https://github.com/your-tools/ruplacer) all mentions of "pytemplate" to your own project's name.
+
+## Installation
+
+To install the project, clone the repository and run:
+
+```sh
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip setuptools
+pip install -r requirements.txt
+pre-commit install
+```
+
+Then install the project using:
+
+```sh
+pip install -e .
+```
+
+See `Makefile` for other useful commands.
+
+## Testing
+
+Just issue `pytest` from the root directory.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

@@ -0,0 +1,37 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here.
+import pathlib
+import sys
+
+sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "pytemplate"
+project_copyright = "2023, Author"
+author = "Author"
+release = "0.0.1"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+]
+
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"

docs/source/index.rst

@@ -0,0 +1,51 @@
+pytemplate
+==========
+
+Demo Sphinx site for the `CQCL pytemplate <https://github.com/CQCL/pytemplate>`_ project.
+
+----
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+Installation
+------------
+
+To install pytemplate, simply run:
+
+.. code-block:: bash
+
+   pip install pytemplate
+
+Usage
+-----
+
+To use pytemplate, import the main module:
+
+.. code-block:: python
+
+   from pytemplate import main
+
+   main.run()
+
+Utils
+-----
+
+The utils module contains various utility functions that can be used in conjunction with pytemplate. To use the utils module, import it like so:
+
+.. code-block:: python
+
+   from pytemplate import utils
+
+   utils.do_something()
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`