code review

.github/workflows/ci.yaml

@@ -1,16 +1,15 @@
-name: ci
+name: CI
 
 on:
   push:
     tags:
-      - "[0-9].[0-9].[0-9]*"
+      - "v*.*.*"
     branches:
       - "main"
       - "release/**"
   pull_request:
     paths:
       - .github/workflows/ci.yaml
-      - hatch.toml
       - pyproject.toml
       - tests/**
       - wizard_template/**
@@ -23,6 +22,7 @@ concurrency:
 
 jobs:
   qa:
+    # Static code analysis and linting powered by pre-commit
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -86,7 +86,7 @@ jobs:
 
   release:
     needs: build
-    # upload to PyPI on every tag
+    # upload to PyPI on every tag and ensure it does not run on forks
     if: github.event_name == 'push' && github.ref_type == 'tag' && github.repository == 'fschuch/wizard_template'
     runs-on: ubuntu-latest
     environment:

.github/workflows/docs.yaml

@@ -5,7 +5,7 @@ name: Docs
 on:
   push:
     tags:
-      - "[0-9].[0-9].[0-9]*"
+      - "v*.*.*"
     branches:
       - main
       - release/**
@@ -14,7 +14,6 @@ on:
       - .github/workflows/docs.yaml
       - docs/**
       - wizard_template/**
-      - hatch.toml
       - pyproject.toml
 
 jobs:

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/conf.py
 
 # PyBuilder
 .pybuilder/

docs/_config.yml

@@ -28,5 +28,25 @@ repository:
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
 html:
+  home_page_in_navbar: false
+  use_edit_page_button: true
   use_issues_button: true
   use_repository_button: true
+
+sphinx:
+  extra_extensions:
+    - sphinx.ext.autodoc
+    - sphinx.ext.intersphinx
+    - sphinx.ext.napoleon
+  config:
+    #https://github.com/executablebooks/jupyter-book/issues/1950#issuecomment-1454801479
+    suppress_warnings: ["mystnb.unknown_mime_type"]
+
+    intersphinx_mapping:
+      python:
+        - "https://docs.python.org/3"
+        - null
+
+    napoleon_include_special_with_doc: true
+    napoleon_google_docstring: False
+    napoleon_numpy_docstring: True

docs/_toc.yml

@@ -3,7 +3,12 @@
 
 format: jb-book
 root: intro
-chapters:
-  - file: markdown
-  - file: notebooks
-  - file: markdown-notebooks
+parts:
+  - caption: Base
+    chapters:
+      - file: markdown
+      - file: notebooks
+      - file: markdown-notebooks
+  - caption: References
+    chapters:
+      - file: api-reference.rst

docs/api-reference.rst

@@ -0,0 +1,10 @@
+API reference
+==================
+
+
+Core
+----
+
+.. automodule:: wizard_template.core
+   :members:
+   :show-inheritance:

pyproject.toml

@@ -1,6 +1,11 @@
+
+[build-system]
+requires = ["hatchling>=1.21.0", "hatch-vcs>=0.3.0"]
+build-backend = "hatchling.build"
+
 [project]
 name = "wizard-template"
-description = "A template for a python project containing a library, tests, docs, and CI/CD."
+description = "A template for a python project containing a package, tests, docs, and CI/CD."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.8"
@@ -9,7 +14,6 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
-    "Private :: Do Not Upload",               # Prevent accidental upload to PyPI, remove before publishing
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -68,6 +72,49 @@ exclude = ["docs/conf.py"]
 skip = "docs/conf.py"
 check-filenames = true
 
-[build-system]
-requires = ["hatchling>=1.21.0", "hatch-vcs>=0.3.0"]
-build-backend = "hatchling.build"
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "wizard_template/_version.py"
+
+[tool.hatch.envs.default]
+installer = "uv"
+description = "Base development environment"
+dependencies = ["coverage[toml]", "pre-commit", "pytest-cov", "pytest"]
+
+[tool.hatch.envs.default.scripts]
+_wizard = ["python ./scripts/rename_project_content.py"]
+pre-commit-install = "pre-commit install {args}"
+pre-commit-uninstall = "pre-commit uninstall {args}"
+check = "pre-commit run {args} --all-files"
+type = "check mypy {args}"
+lint = "check ruff {args}"
+format = "check ruff-format {args}"
+test = "pytest --cov --cov-report=term {args}"
+test-no-cov = "test --no-cov {args}"
+qa = ["check", "test", "echo '✅ QA passed'"]
+
+[tool.hatch.envs.test]
+description = "Extended test environment"
+extra-dependencies = ["pytest-randomly", "pytest-rerunfailures", "pytest-xdist"]
+
+[tool.hatch.envs.test.scripts]
+extended = "test -n auto --reruns 7 --reruns-delay 1 {args}"
+
+[[tool.hatch.envs.test.matrix]]
+python = ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+[tool.hatch.envs.docs]
+description = "Documentation environment"
+template = "docs"
+install = true
+dependencies = ["docutils", "jupyter-book", "sphinx-autobuild"]
+
+[tool.hatch.envs.docs.scripts]
+config = "jupyter-book config sphinx docs {args}"
+build = ["config", "jupyter-book build docs --path-output build {args}"]
+serve = [
+    "config",
+    "sphinx-autobuild docs build/_build/html --open-browser --watch wizard_template {args}",
+]

scripts/rename_project_content.py

@@ -19,6 +19,16 @@
 CWD = Path.cwd()
 THIS_FILE = Path(__file__)
 
+COMMUNITY_BADGE_TEMPLATE = (
+    "[![Wizard Template]"
+    "(https://img.shields.io/badge/Wizard-Template-%23447CAA)]"
+    "(https://github.com/{}/{})"
+)
+
+ORIGINAL_BADGE = COMMUNITY_BADGE_TEMPLATE.format(
+    ORIGINAL_USERNAME, ORIGINAL_PROJECT_NAME
+)
+
 
 class GitInfo(NamedTuple):
     """Named tuple to store the git info."""
@@ -49,7 +59,7 @@ def from_repo_info_with_fallback() -> GitInfo:
     """Get the repository information."""
     try:
         return GitInfo.from_repo_info()
-    except ValueError:
+    except (ValueError, subprocess.CalledProcessError):
         print("Could not parse git URL, please enter the information manually.")
         username = input("Enter your username: ")
         repo = input("Enter your repo: ")
@@ -67,6 +77,8 @@ def main() -> None:
     project_name_dash = project_name.replace("_", "-")
     project_name_underscore = project_name.replace("-", "_")
 
+    tmp_badge = COMMUNITY_BADGE_TEMPLATE.format(username, project_name)
+
     # Map new values to the patterns to be replaced
     patterns = {
         username: re.compile(ORIGINAL_USERNAME),
@@ -88,6 +100,9 @@ def main() -> None:
         for new_value, pattern in patterns.items():
             filedata = pattern.sub(new_value, filedata)
 
+        # Revert back the badge to support the original project
+        filedata = filedata.replace(tmp_badge, ORIGINAL_BADGE)
+
         # Write the file out again
         filepath.write_text(filedata)
 

wizard_template/core.py

@@ -15,15 +15,18 @@ def demo_function(incoming_int: int) -> int:
 
     Args
     ----
-    incoming_int: The input to be doubled.
+    incoming_int
+        The input to be doubled
 
     Returns
     -------
-    The doubled input.
+    int
+        The doubled input
 
     Raises
     ------
-    TypeError: If the input is not an integer.
+    NotAnIntegerError
+        If tried with an invalid input
 
     Examples
     --------