Merge pull request #1 from chris-santiago/toml

Toml
chris-santiago · Dec 17, 2022 · 9ec8f7a · 9ec8f7a
2 parents 9a08038 + 6f5f2a8
commit 9ec8f7a
Show file tree

Hide file tree

Showing 18 changed files with 516 additions and 214 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,11 +1,39 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
-################## Base ##################
--   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.2.0
-    hooks:
-    -   id: trailing-whitespace
-    -   id: end-of-file-fixer
-    -   id: check-yaml
-    -   id: check-added-large-files
+# -------------------- Base --------------------
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+        types: [file]
+      - id: end-of-file-fixer
+        types: [file]
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: debug-statements
+  # -------------------- iSort --------------------
+  - repo: https://github.com/PyCQA/isort
+    rev: v5.11.3
+    hooks:
+      - id: isort
+        types: [ python ]
+  # -------------------- Black --------------------
+  - repo: https://github.com/psf/black
+    rev: 22.12.0
+    hooks:
+      - id: black
+        types: [file, python]
+  # -------------------- Flake8 --------------------
+  - repo: https://github.com/PyCQA/flake8
+    rev: 6.0.0
+    hooks:
+      - id: flake8
+        additional_dependencies: [ flake8-docstrings ]
+        args: [
+            '--count',
+            '--statistics',
+            '--exit-zero',
+            '--show-source',
+            '--max-line-length', '100',
+        ]
diff --git a/README.md b/README.md
@@ -13,30 +13,110 @@ We use [nox](https://nox.thea.codes/en/stable/), rather than tox, to automate ou
 4. We can automate documentation builds in our *current* Python environment, vice a virtual environment, meaning that our docs will build in our package/docs folder, rather than the .tox/venv/ folder.
 5. We can remove `Makefiles` (an issue for Windows users) and run the commands in `noxfile.py`.
 
-### Setup.cfg vs Setup.py
+### Pyproject.toml
 
-We've moved much of the metadata and package options to the `setup.cfg` file, which is inherently declarative. This also means we don't use a `requirements.txt` file; users should list their package requirements in the `setup.cfg` file, under the `[options]install_requires=` section.
+We've moved much of the metadata and package options to the `pyproject.toml` file, which is inherently declarative. This also means we don't use a `requirements.txt` file; users should list their package requirements in the `pyproject.toml` file, under the `[project]dependencies=` section.
 
-We've also consolidated configuration files (pytest.ini, .pylintrc, etc) into the `setup.cfg` file.
+We've also consolidated configuration files (pytest.ini, .pylintrc, etc) into the `pyproject.toml` file.
+
+**Note:** Flake8 doesn't support `pyproject.toml`, so its configuration is set during invocation. Arguments are found in the `.pre-commit-config.yaml` and `noxfile.py` files.
 
 ## Noxfile
 
 The Noxfile will run several tests and commands:
 
 - Pytest in current Python environment
+- Pytest in all supported Python environments
+- Mypy
 - Pylint
 - Flake8
-- Mypy
-- Sphinx-apidoc
-- Sphinx-build
-- Check-manifest
 - iSort
+- Black
+- Check-manifest
 - Pre-commit trailing-whitespace
 - Pre-commit end-of-file-fixer
+- Pre-commit check-yaml
+- Sphinx-apidoc
+- Sphinx-build
 
 Pytest coverage lands in ./htmlcov
 Documentation lands in ./docs/build and ./docs/source
 
+### Nox Configuration
+
+By default, the command `nox` will run sessions under the `"pytest"` and `"qa"` tags.  These include: Pytest in current Python environment, Mypy, Pylint, Flake8, iSort, Black and Pre-commit trailing-whitespace/end-of-file-fixer/check-yaml.
+
+Example:
+
+```bash
+> nox
+
+nox > Ran multiple sessions:
+nox > * test_system_python: success
+nox > * mypy: success
+nox > * pylint: success
+nox > * flake8: success
+nox > * isort: success
+nox > * black: success
+nox > * precommit: success
+```
+
+#### Other Tags
+
+The `quick` tag will run Pytest in current Python environment and Flake8.
+
+Example:
+
+```bash
+> nox -t quick
+
+nox > Ran multiple sessions:
+nox > * test_system_python: success
+nox > * flake8: success
+```
+
+The `pytest` tag will run Pytest in current Python environment, only.
+
+Example:
+
+```bash
+> nox -t pytest
+
+nox > Session test_system_python was successful.
+```
+
+The `tests` tag will run Pytest in all supported Python environments.
+
+Example:
+
+```bash
+> nox -t tests
+
+nox > Ran multiple sessions:
+nox > * test_supported_python-3.8: success
+nox > * test_supported_python-3.9: success
+```
+
+The `pre-release` tag runs all sessions, including documentation build, but **excluding** Pytest in the current Python environment (it will test all supported environments, instead).
+
+Example:
+
+```bash
+> nox -t pre-release
+
+nox > Ran multiple sessions:
+nox > * test_supported_python-3.8: success
+nox > * test_supported_python-3.9: success
+nox > * mypy: success
+nox > * pylint: success
+nox > * flake8: success
+nox > * isort: success
+nox > * black: success
+nox > * manifest: success
+nox > * precommit: success
+nox > * docs: success
+```
+
 ## Installation
 
 ### Setup a new environment
@@ -58,6 +138,16 @@ create a new project directory using your response to the `project_slug` prompt.
 
 ### Install Project
 
+#### Quick initialization
+We've included an `init.sh` file to quickly install your project (editable), update and install pre-commit.
+
+- Navigate to your project's directory (i.e. `cd yourdirectoryhere`).
+- Run `bash init.sh`
+
+#### Manual initialization
+
+Alternatively, you can complete these same steps one-by-one.  Omit `pre-commit`, if desired.
+
 - Navigate to your project's directory (i.e. `cd yourdirectoryhere`).
 - Install project in editable mode, with dev requirements: `pip install -e. [docs,tests,qa,build]`.
 - Initialize project as a git repo: `git init`.
@@ -67,31 +157,55 @@ create a new project directory using your response to the `project_slug` prompt.
 - Run nox: `nox`
 
 ```bash
-cd yourproject
-pip install -e .[docs,tests,qa,build]
-git init
-pre-commit install
-git add --all
-git commit -m "initial"
-nox
+> cd yourproject
+> pip install -e ."[dev]"
+> git init
+> pre-commit autoupdate
+> pre-commit install
+```
+
+#### First commit:
+
+If you're usinging pre-commit, your first commit will look something like this:
+
+```bash
+> git add --all
+> git commit -m "initial"
+
+trim trailing whitespace.................................................Passed
+fix end of files.........................................................Passed
+check yaml...............................................................Passed
+check for added large files..............................................Passed
+debug statements (python)................................................Passed
+isort....................................................................Passed
+black....................................................................Passed
+flake8...................................................................Passed
 ```
 
+#### First Nox run:
+
+The first `nox` run is fairly quick as we're not creating any separate test environment, by default.  However, the first time you run the `tests` or `pre-release` tag will take some time as new environments are build; subsequent runs will be much faster as we reuse these virtual (conda) environments, by default.
+
 You'll see **a lot** of output:
 
 ```bash
-nox > Running session test_prod_python
-nox > Re-using existing conda env at .nox/test_prod_python.
-nox > python -m pip install pytest pytest-cov
-nox > python -m pip install .
-nox > pytest 
+> nox
+
+nox > Running session test_system_python
+nox > pytest
+nox > Session test_system_python was successful.
+nox > Running session mypy
+nox > mypy --install-types --non-interactive -p python_project
+Success: no issues found in 2 source files
 ...
 ...
 ...
-nox > Session docs was successful.
 nox > Ran multiple sessions:
-nox > * test_prod_python: success
-nox > * test_current: success
-nox > * lint: success
-nox > * qa: success
-nox > * docs: success
+nox > * test_system_python: success
+nox > * mypy: success
+nox > * pylint: success
+nox > * flake8: success
+nox > * isort: success
+nox > * black: success
+nox > * precommit: success
 ```
diff --git a/cookiecutter.json b/cookiecutter.json
@@ -1,5 +1,5 @@
 {
-  "python_version": ["3.7", "3.8", "3.9"],
+  "python_requires": ["3.8", "3.9", "3.10", "3.11"],
   "project_name": "Python Project",
   "project_author": "Chris Santiago",
   "author_email": "cjsantiago@gatech.edu",

diff --git a/{{cookiecutter.project_slug}}/.pre-commit-config.yaml b/{{cookiecutter.project_slug}}/.pre-commit-config.yaml
@@ -1,31 +1,41 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
-# -------------------- Base --------------------
--   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.2.0
+  # -------------------- Base --------------------
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: stable
     hooks:
-    -   id: trailing-whitespace
-        files: .py$
-        exclude: tests/
-    -   id: end-of-file-fixer
-        files: .py$
-        exclude: tests/
-    -   id: check-yaml
-    -   id: check-added-large-files
-# -------------------- iSort --------------------
--   repo: https://github.com/PyCQA/isort
+      - id: trailing-whitespace
+#        exclude: (^tests/|^docs/)
+      - id: end-of-file-fixer
+#        exclude: (^tests/|^docs/)
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: debug-statements
+  # -------------------- iSort --------------------
+  - repo: https://github.com/PyCQA/isort
     rev: 5.9.2
     hooks:
-    -   id: isort
-# -------------------- Flake8 --------------------
--   repo: https://github.com/PyCQA/flake8
-    rev: 3.8.3
+      - id: isort
+        types: [ python ]
+  # -------------------- Black --------------------
+  - repo: https://github.com/psf/black
+    rev: stable
     hooks:
-    -   id: flake8
-        args: ['--count', '--statistics', '--exit-zero', ' --show-source']
-# -------------------- Manifest --------------------
--   repo: https://github.com/mgedmin/check-manifest
-    rev: '0.46'
+      - id: black
+        types: [file, python]
+        exclude: (^tests/|^docs/)
+  # -------------------- Flake8 --------------------
+  - repo: https://github.com/PyCQA/flake8
+    rev: stable
     hooks:
-    -   id: check-manifest
+      - id: flake8
+        additional_dependencies: [ flake8-docstrings ]
+        exclude: (^tests/|^docs/)
+        args: [
+            '--count',
+            '--statistics',
+            '--exit-zero',
+            '--show-source',
+            '--max-line-length', '100',
+        ]
diff --git a/{{cookiecutter.project_slug}}/CHANGELOG.md b/{{cookiecutter.project_slug}}/CHANGELOG.md
@@ -0,0 +1,4 @@
+# Changelog
+
+## 0.1.0
+The initial setup of this project.
diff --git a/{{cookiecutter.project_slug}}/DESCRIPTION.md b/{{cookiecutter.project_slug}}/DESCRIPTION.md
diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md
@@ -2,10 +2,15 @@
 
 ## Install
 
-Create a virtual environment with Python {{cookiecutter.python_version}} and install from git:
+Create a virtual environment with Python >= {{cookiecutter.python_requires}} and install from git:
 
 ```bash
 pip install {{cookiecutter.project_github_pip}}
 ```
 
 ## Use
+
+
+## Documentation
+
+Documentation hosted on Github Pages: [https://chris-santiago.github.io/{{cookiecutter.project_slug}}/](https://chris-santiago.github.io/{{cookiecutter.project_slug}}/)
diff --git a/{{cookiecutter.project_slug}}/docs/source/changelog.md b/{{cookiecutter.project_slug}}/docs/source/changelog.md
@@ -0,0 +1,3 @@
+
+```{include} ../../CHANGELOG.md
+```