Merge pull request #3 from qartik/updates-23-oct

Updates, add Makefile, typos and ruff.toml

.dockerignore

@@ -4,4 +4,4 @@ __pycache__
 *.pyd
 *.egg-info
 dist
-build
+build

.github/workflows/python-app.yml

@@ -36,11 +36,11 @@ jobs:
     # - name: Sphinx documentation build
     #   run: |
     #     python -m pip install sphinx
-    #     sphinx-build -b html docs/ docs/_build/
+    #     sphinx-build -M html docs/source/ docs/build/
 
     # - name: Build and push Docker image
     #   uses: docker/build-push-action@v2
     #   with:
     #     context: .
     #     push: true
-    #     tags: nathfitz/test:latest
+    #     tags: nathfitz/test:latest

.gitignore

@@ -12,4 +12,4 @@ __pypackages__/
 *.swp
 .DS_Store
 .qtmlib/
-*.venv/
+*.venv/

.pre-commit-config.yaml

@@ -1,23 +1,34 @@
 repos:
-  - repo: https://github.com/psf/black
-    rev: 23.7.0
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
     hooks:
-      - id: black
+      - 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/RobertCraigie/pyright-python
-    rev: v1.1.317
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.16.17
     hooks:
-      - id: pyright
+      - id: typos
+
+  - repo: https://github.com/psf/black
+    rev: 23.9.1
+    hooks:
+      - id: black
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.278
+    rev: v0.0.292
     hooks:
       - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
 
-# Building docs on precommit seems like this will be slow.
-# - repo: https://github.com/pre-commit/mirrors-sphinx
-#   rev: v4.2.0
-#   hooks:
-#   - id: sphinx
-#     stages: [commit]
-#     language_version: python3.11
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.329
+    hooks:
+      - id: pyright

Dockerfile

@@ -10,4 +10,4 @@ COPY . .
 RUN pip install --no-cache-dir -r requirements.txt
 
 # Start the web server
-CMD ["python", "-m", "pytemplate.main"]
+CMD ["python", "-m", "pytemplate.main"]

Makefile

@@ -0,0 +1,22 @@
+.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-build -M html docs/source/ docs/build/
+
+clean:
+	rm -rf *.egg-info dist build
+
+build: clean
+	python -m build --sdist -n

README.md

@@ -1,52 +1,55 @@
 # pytemplate
 
-This is a Python 3.11 app called pytemplate. It uses toml instead of setup.py for configuration. The project includes Docker, Pyright, Ruff, GitHub Actions, Black, pre-commit, and Sphinx.
+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
-├── .github
-│   └── workflows
-│       └── python-app.yml
-├── .pre-commit-config.yaml
-├── .vscode
-│   ├── launch.json
-│   └── settings.json
-├── docs
-│   ├── conf.py
-│   ├── index.rst
-│   └── _static
-├── qtmlib
-│   ├── __init__.py
-│   ├── main.py
-│   └── utils.py
-├── tests
-│   ├── __init__.py
-│   ├── test_main.py
-│   └── test_utils.py
 ├── .dockerignore
+├── .github
+│   └── workflows
+│       └── python-app.yml
 ├── .gitignore
+├── .pre-commit-config.yaml
 ├── Dockerfile
-├── pyproject.toml
+├── Makefile
 ├── README.md
-└── requirements.txt
+├── 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 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 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` file.
+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 `conf.py` file contains the configuration for Sphinx.
+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
+
+Change references to "pytemplate" and "qtmlib" for your own project.
+
 ## Installation
 
 To install the project, clone the repository and run:
@@ -65,6 +68,8 @@ Then install the project using:
 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,25 @@
+# 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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "qtmlib"
+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 = []
+
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"

docs/index.rst → docs/source/index.rst

@@ -5,10 +5,6 @@ qtmlib
    :maxdepth: 2
    :caption: Contents:
 
-   installation
-   usage
-   utils
-
 Installation
 ------------
 
@@ -38,4 +34,11 @@ The utils module contains various utility functions that can be used in conjunct
 
    from qtmlib import utils
 
-   utils.do_something()
+   utils.do_something()
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

pyproject.toml

@@ -6,21 +6,15 @@ build-backend = "setuptools.build_meta"
 name = "pytemplate"
 version = "0.0.1"
 description = "A python library"
+readme = "README.md"
 requires-python = ">=3.11"
 authors = [{name = "Author", email = "author@email.com" }]
 
 [tool.setuptools.packages.find]
 where = ["."]
 
-[tool.ruff]
-# See https://beta.ruff.rs/docs/rules/
-select = ["E", "F", "B", "RUF", "PT", "UP", "C4", "D"]
-extend-exclude = ["**/*.ipynb"]
-target-version = "py311"
-
-[tool.ruff.pydocstyle]
-# Use Google-style docstrings.
-convention = "google"
+[project.urls]
+Repository = "https://github.com/CQCL/pytemplate.git"
 
 # See https://microsoft.github.io/pyright/#/getting-started
 [tool.pyright]

requirements.txt

@@ -1,7 +1,7 @@
 black
+build
 pre-commit
 pyright
 pytest
-pytest-lazy-fixture
 sphinx
 wheel

ruff.toml

@@ -0,0 +1,60 @@
+# See https://docs.astral.sh/ruff/rules/
+target-version = "py311"
+
+line-length = 88
+
+select = [
+  "E",    # pycodestyle Errors
+  "W",    # pycodestyle Warnings
+
+  "A",    # flake8-builtins
+  "B",    # flake8-Bugbear
+  "BLE",  # flake8-blind-except
+  "C4",   # flake8-comprehensions
+  "COM",  # flake8-commas
+  "D",    # pydocstyle
+  "EM",   # flake8-errmsg
+  "EXE",  # flake8-executable
+  "F",    # pyFlakes
+  "FA",   # flake8-future-annotations
+  "FIX",  # flake8-fixme
+  "FLY",  # flynt
+  "G",    # flake8-logging-format
+  "I",    # isort
+  "INP",  # flake8-no-pep420
+  "ISC",  # flake8-implicit-str-concat
+  "N",    # pep8-Naming
+  "NPY",  # NumPy-specific
+  "PERF", # Perflint
+  "PGH",  # pygrep-hooks
+  "PIE",  # flake8-pie
+  "PL",   # pylint
+  "PT",   # flake8-pytest-style
+  "RSE",  # flake8-raise
+  "RUF",  # Ruff-specific
+  "S",    # flake8-bandit (Security)
+  "SIM",  # flake8-simplify
+  "SLF",  # flake8-self
+  "SLOT", # flake8-slots
+  "T10",  # flake8-debugger
+#   "T20",  # flake8-print
+  "TD",   # flake8-todos
+  "TRY",  # tryceratops
+  "UP",   # pyupgrade
+  "YTT",  # flake8-2020
+]
+
+[per-file-ignores]
+"__init__.py" = ["F401"]    # module imported but unused
+"docs/*"      = [
+    "D100",     # Missing docstring in public module
+    "INP001",   # File * is part of an implicit namespace package. Add an `__init__.py`.
+]
+"tests/*"     = [
+    "INP001",
+    "S101",     # Use of `assert` detected
+    "PLR2004",  # Magic value used in comparison, consider replacing * with a constant variable
+    ]
+
+[pydocstyle]
+convention = "google"