Merge pull request #15

Small CI Changes

Author: 56kyle

docs/conf.py

@@ -5,60 +5,39 @@
 from datetime import date
 
 
-# --- Project information -----------------------------------------------------
-
-# General info about the TEMPLATE documentation itself
 project = "cookiecutter-robust-python Template Documentation"
-# Copyright year and author name
-copyright = f"{date.today().year}, Kyle Oliver"  # Dynamically get current year
+copyright = f"{date.today().year}, Kyle Oliver"  # noqa
 
-# Author name
 author = "Kyle Oliver"
 
-# The version info for the TEMPLATE. Using Calendar Versioning: YYYY.MM.DD
-# **UPDATE MANUALLY OR VIA SIMPLE SCRIPT WITH EACH TEMPLATE RELEASE**
-# This version tracks the template"s development state, not generated projects.
-release = "2025.04.28"  # Example: YYYY.MM.DD - **UPDATE MANUALLY**
-# The short X.Y version for the template (YYYY.MM)
-version = "2025.04"  # Example: YYYY.MM - **UPDATE MANUALLY**
+release = "2025.04.28"
+version = "2025.04"
 
 extensions = [
-    "sphinx.ext.intersphinx",  # Link to documentation of other projects
-    "sphinx.ext.napoleon",  # Support for Google and NumPy style docstrings (useful for understanding code mentioned)
-    "myst_parser",  # Support for parsing Markdown files (.md)
-    "sphinx_autodoc_typehints",  # Better rendering of type hints (useful for understanding code mentioned/evaluated)
-    "sphinx_copybutton",  # Adds a "copy" button to code blocks (Excellent QoL)
-    "sphinx_tabs.tabs",  # Adds tab support (Useful for showing OS-specific commands/configs, code variants)
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "sphinx_autodoc_typehints",
+    "sphinx_copybutton",
+    "sphinx_tabs.tabs",
 ]
-templates_path = ["_templates"]  # Create this directory if needed
+templates_path = ["_templates"]
 
-# List of patterns relative to source directory, that match files/directories to ignore.
 exclude_patterns = [
-    "_build",  # Output directory
-    "Thumbs.db",  # MacOS files
-    ".DS_Store",  # MacOS files
-    ".venv",  # Standard virtual environment directory
-    ".nox",  # Nox environment directory (for template docs build)
-    # EXCLUDE THE GENERATED PROJECT TEMPLATE DIRECTORY ITSELF!!
-    # Sphinx runs from "docs/" directory, so path is relative to there "../{{ cookiecutter.project_slug }}"
-    # The {{ cookiecutter.project_slug }} variable is not available here at TEMPLATE doc build time.
-    # You need to manually exclude the directory name based on your typical generated slug structure or use a simpler pattern
-    # Assuming the generated slug will likely be lowercase/hyphenated based on cookiecutter.json logic
-    # e.g., exclude patterns like "my-robust-python-project", "another-project-name"
-    # Alternatively, exclude based on path structure if generated output goes to a known sibling dir
-    # A simple solution for template docs is to manually add generated projects to this list if they cause build issues.
-    # For robust template docs, you"d build from the template root and exclude the *rendered* output dir of the generated project.
-    # Let"s just exclude common development/build environment dirs and rely on the build process to only target the "docs/" dir.
-    "rust",  # Exclude example Rust source dir at template root
-    "tests",  # Exclude template"s own tests if any (e.g., tests/ directory at template root)
-    "cookiecutter.json",  # Exclude the cookiecutter input file itself from being treated as a doc source
-    "README.md",  # Exclude the template"s README file from being treated as a doc source
-    "noxfile.py",  # Exclude the template"s noxfile
-    ".pre-commit-config.yaml",  # Exclude template"s pre-commit config
-    "pyproject.toml",  # Exclude the template"s pyproject.toml
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    ".venv",
+    ".nox",
+    "rust",
+    "tests",
+    "cookiecutter.json",
+    "README.md",
+    "noxfile.py",
+    ".pre-commit-config.yaml",
+    "pyproject.toml",
 ]
 
-# MyST-Parser settings (allows using Markdown + Sphinx features)
 myst_enable_extensions = [
     "amsmath",
     "colon_fence",
@@ -75,64 +54,41 @@
     "attrs_block",
 ]
 
-# Intersphinx mapping: Link to documentation of standard libraries or tools mentioned
-# Tuple: (base URL, inventory file path/None for standard)
-# Ensure URLs end with / and are correct. Use "latest" or "stable" versions often.
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "pip": ("https://pip.pypa.io/en/stable/", None),
 }
 
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML output
 html_theme = "furo"
-
-# Add any paths that contain custom static files (like logo, css).
-html_static_path = ["_static"]  # Create this directory (docs/_static) if you add files like logo.png
-
-# HTML theme options (example for Furo)
+html_static_path = ["_static"]
 html_theme_options = {
-    # Create docs/_static/logo-light.png and logo-dark.png
-    "sidebar_hide_name": True,  # Hide project name next to logo if logo contains it
-    # "light_logo": "logo-light.png",
-    # "dark_logo": "logo-dark.png",
-    # Footer icons
+    "sidebar_hide_name": True,
     "footer_icons": [
         {
             "name": "GitHub",
             "url": "https://github.com/56kyle/cookiecutter-robust-python",
-            # **UPDATE THIS URL IF TEMPLATE REPO CHANGES**
             "html": "<svg stroke='currentColor' fill='currentColor' stroke-width='0' viewBox='0 0 16 16'><path fill-rule='evenodd' d='M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.22.82.69 1.19 1.81.85 2.23.65.07-.51.28-.85.54-1.04-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38C13.71 14.53 16 11.53 16 8c0-4.42-3.58-8-8-8z'></path></svg>",
             "aria-label": "GitHub",
         },
     ],
-    # Configure links back to the source repo itself
     "source_repository": "https://github.com/56kyle/cookiecutter-robust-python/",
-    # **UPDATE THIS URL IF TEMPLATE REPO CHANGES**
-    "source_branch": "main",  # Or your default branch
-    "source_directory": "docs/",  # Tells Furo that the doc source is in this subdir relative to repo root
+    "source_branch": "main",
+    "source_directory": "docs/",
 }
 
-# -- Options for Napoleon -----------------------------------------------------
-# Ensure Napoleon processes Google style docstrings correctly
-napoleon_google_docstrings = True  # Enable Google style (Parameters, Returns, etc.)
-napoleon_numpy_docstrings = False  # Disable NumPy style if not used
-napoleon_include_init_with_doc = False  # Set to true if __init__ only calls super() but has docstrings
-napoleon_include_private_with_doc = False  # Include private members with docstrings if needed
-napoleon_include_special_with_doc = True  # Include special members (__str__, etc.)
-napoleon_use_admonition_for_examples = True  # Render Examples sections as admonitions (Recommended)
-napoleon_use_admonition_for_notes = True  # Render Notes sections as admonitions (Recommended)
-napoleon_use_admonition_for_references = True  # Render References sections as admonitions (Recommended)
-# Control parameter list format: use keyword is often nicer
-napoleon_use_keyword = True  # Use :keyword: role (aligns with Google style recommendation)
-napoleon_use_param = True  # Use :param: role
-napoleon_use_rtype = True  # Use :rtype: role (Recommended when using type hints)
-napoleon_attr_annotations = True  # Document attributes with type annotations
+napoleon_google_docstrings = True
+napoleon_numpy_docstrings = False
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = True
+napoleon_use_keyword = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_attr_annotations = True
 
-# -- Options for sphinx-autodoc-typehints -------------------------------------
-# This extension handles displaying type hints correctly and adds type annotation to Parameters/Returns sections
-# https://sphinx-autodoc-typehints.readthedocs.io/en/stable/
 set_type_checking_flag = True
 always_document_param_types = False
 typehints_fully_qualified = False

noxfile.py

@@ -34,23 +34,23 @@
 DEFAULT_DEMO_NAME: str = "robust-python-demo"
 DEMO_ROOT_FOLDER: Path = PROJECT_DEMOS_FOLDER / DEFAULT_DEMO_NAME
 
-GENERATE_DEMO_PROJECT_SCRIPT: Path = SCRIPTS_FOLDER / "generate-demo-project.py"
-GENERATE_DEMO_PROJECT_OPTIONS: tuple[str, ...] = (
+GENERATE_DEMO_SCRIPT: Path = SCRIPTS_FOLDER / "generate-demo.py"
+GENERATE_DEMO_OPTIONS: tuple[str, ...] = (
     *("--repo-folder", REPO_ROOT),
     *("--demos-cache-folder", PROJECT_DEMOS_FOLDER),
     *("--demo-name", DEFAULT_DEMO_NAME),
 )
 
 
 LINT_FROM_DEMO_SCRIPT: Path = SCRIPTS_FOLDER / "lint-from-demo.py"
-LINT_FROM_DEMO_OPTIONS: tuple[str, ...] = GENERATE_DEMO_PROJECT_OPTIONS
+LINT_FROM_DEMO_OPTIONS: tuple[str, ...] = GENERATE_DEMO_OPTIONS
 
 
-@nox.session(name="generate-demo-project", python=DEFAULT_TEMPLATE_PYTHON_VERSION)
-def generate_demo_project(session: Session) -> None:
+@nox.session(name="generate-demo", python=DEFAULT_TEMPLATE_PYTHON_VERSION)
+def generate_demo(session: Session) -> None:
     """Generates a project demo using the cookiecutter-robust-python template."""
     session.install("cookiecutter", "platformdirs", "loguru", "typer")
-    session.run("python", GENERATE_DEMO_PROJECT_SCRIPT, *GENERATE_DEMO_PROJECT_OPTIONS, *session.posargs)
+    session.run("python", GENERATE_DEMO_SCRIPT, *GENERATE_DEMO_OPTIONS, *session.posargs)
 
 
 @nox.session(name="clear-cache", python=None)
@@ -123,7 +123,6 @@ def test(session: Session) -> None:
     session.run("pytest", "tests")
 
 
-
 @nox.session(venv_backend="none")
 def release_template(session: Session):
     """Run the release process for the TEMPLATE using Commitizen.

scripts/generate-demo-project.py scripts/generate-demo.pyscripts/generate-demo-project.py renamed to scripts/generate-demo.py

@@ -7,7 +7,7 @@
 import typer
 
 from util import FolderOption
-from util import generate_demo_project
+from util import generate_demo
 
 
 cli: typer.Typer = typer.Typer()
@@ -22,7 +22,7 @@ def main(
 ) -> None:
     """Updates the poetry.lock file."""
     try:
-        generate_demo_project(
+        generate_demo(
             repo_folder=repo_folder,
             demos_cache_folder=demos_cache_folder,
             demo_name=demo_name,

scripts/util.py

@@ -56,7 +56,7 @@ def in_new_demo(
     **kwargs: Any
 ) -> Generator[Path, None, None]:
     """Returns a context manager for working within a new demo."""
-    demo_path: Path = generate_demo_project(
+    demo_path: Path = generate_demo(
         repo_folder=repo_folder,
         demos_cache_folder=demos_cache_folder,
         demo_name=demo_name,
@@ -67,7 +67,7 @@ def in_new_demo(
         yield demo_path
 
 
-def generate_demo_project(
+def generate_demo(
     repo_folder: Path,
     demos_cache_folder: Path,
     demo_name: str,

{{cookiecutter.project_name}}/.github/workflows/test-python.yml

@@ -54,7 +54,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: {{"test-results-${{ matrix.os }}-py${{ matrix.python-version }}"}}
-          path: test-results/*.xml
+          path: tests/results/*.xml
           retention-days: 5
 
       - name: Upload coverage report

{{cookiecutter.project_name}}/.gitignore

@@ -37,7 +37,7 @@ build/         # Build artifacts from setuptools/build backends
 htmlcov/       # Coverage HTML reports (default output dir)
 .coverage*     # Coverage data files (default name pattern)
 coverage.*
-test-results/  # Directory for JUnit/Coverage XML reports (as configured in noxfile)
+tests/results/  # Directory for JUnit/Coverage XML reports (as configured in noxfile)
 
 # Editor/IDE specific files
 .vscode/       # VS Code settings (if not shared via devcontainer)

{{cookiecutter.project_name}}/.pre-commit-config.yaml

@@ -3,24 +3,49 @@
 default_stages: [pre-commit]
 
 repos:
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+  - repo: local
     hooks:
       - id: check-added-large-files
-        args: ["--maxkb=2000"]
-      - id: check-yaml
+        name: Check for added large files
+        entry: check-added-large-files
+        language: system
       - id: check-toml
+        name: Check Toml
+        entry: check-toml
+        language: system
+        types: [toml]
+      - id: check-yaml
+        name: Check Yaml
+        entry: check-yaml
+        language: system
+        types: [yaml]
+      - id: darglint
+        name: darglint
+        entry: darglint
+        language: system
+        types: [python]
+        stages: [manual]
       - id: end-of-file-fixer
+        name: Fix End of Files
+        entry: end-of-file-fixer
+        language: system
+        types: [text]
+        stages: [pre-commit, pre-push, manual]
       - id: trailing-whitespace
+        name: Trim Trailing Whitespace
+        entry: trailing-whitespace-fixer
+        language: system
+        types: [text]
+        stages: [pre-commit, pre-push, manual]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.11.11
     hooks:
       - id: ruff-format
         args: [--config=.ruff.toml]
 
-      - id: ruff
-        args: [--fix, --exit-non-zero-on-fix, --config=.ruff.toml]
+      - id: ruff-check
+        args: [--fix, --diff, --exit-non-zero-on-fix, --config=.ruff.toml]
 
   - repo: https://github.com/doublify/pre-commit-rust
     rev: master

{{cookiecutter.project_name}}/docs/codeofconduct.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+```{include} ../CODE_OF_CONDUCT.md
+
+```

{{cookiecutter.project_name}}/docs/conf.py

@@ -0,0 +1,57 @@
+"""Sphinx configuration."""
+
+project = "{{cookiecutter.friendly_name}}"
+author = "{{cookiecutter.author}}"
+copyright = "{{cookiecutter.copyright_year}}, {{cookiecutter.author}}"  # noqa
+
+release = "{{cookiecutter.version}}"
+version = ".".join(release.split(".")[:2])
+
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinxcontrib.typer",
+    "myst_parser",
+    "sphinx_autodoc_typehints",
+    "sphinx_copybutton",
+    "sphinx_tabs.tabs",
+]
+templates_path = ["_templates"]
+
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    ".venv",
+    ".nox",
+    "rust",
+    "tests",
+    "cookiecutter.json",
+    "README.md",
+    "noxfile.py",
+    ".pre-commit-config.yaml",
+    "pyproject.toml",
+]
+
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_admonition",
+    "html_image",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+    "attrs_inline",
+    "attrs_block",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "pip": ("https://pip.pypa.io/en/stable/", None),
+}
+
+html_theme = "furo"

{{cookiecutter.project_name}}/docs/contributing.md

@@ -0,0 +1,9 @@
+# Contributing
+
+```{include} ../CONTRIBUTING.md
+---
+end-before: <!-- github-only -->
+---
+```
+
+[code of conduct]: codeofconduct