Skip to content

Commit c33e3b6

Browse files
Magic-Man-usMagic-Man-us
committed
updates for workflows, readme adding badges
1 parent bcbacdb commit c33e3b6

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+7418
-440
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,6 @@ jobs:
118118
continue-on-error: true
119119

120120
- name: Upload security reports
121-
if: always()
122121
uses: actions/upload-artifact@v5
123122
with:
124123
name: security-reports
@@ -157,7 +156,7 @@ jobs:
157156

158157
- name: Deploy to GitHub Pages
159158
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
160-
uses: peaceiris/actions-gh-pages@v3
159+
uses: peaceiris/actions-gh-pages@v4
161160
with:
162161
github_token: ${{ secrets.GITHUB_TOKEN }}
163162
publish_dir: ./docs/_build/html

‎.pre-commit-config.yaml‎

Lines changed: 19 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,28 @@
11
repos:
2-
- repo: https://github.com/pre-commit/pre-commit-hooks
3-
rev: v4.5.0
4-
hooks:
5-
- id: trailing-whitespace
6-
- id: end-of-file-fixer
7-
- id: check-yaml
8-
- id: check-added-large-files
9-
- id: check-merge-conflict
10-
- id: check-toml
11-
122
- repo: https://github.com/astral-sh/ruff-pre-commit
13-
rev: v0.1.6
3+
rev: v0.8.4
144
hooks:
155
- id: ruff
166
args: [--fix]
177
- id: ruff-format
188

19-
- repo: https://github.com/psf/black
20-
rev: 23.11.0
9+
- repo: https://github.com/pre-commit/pre-commit-hooks
10+
rev: v5.0.0
2111
hooks:
22-
- id: black
12+
# Removed trailing-whitespace and end-of-file-fixer to reduce auto-fix noise
13+
- id: check-yaml
14+
- id: check-added-large-files
15+
args: ['--maxkb=1000'] # Allow up to 1MB files
16+
- id: check-toml
2317

24-
- repo: https://github.com/pre-commit/mirrors-mypy
25-
rev: v1.7.0
26-
hooks:
27-
- id: mypy
28-
additional_dependencies:
29-
- pydantic>=2.5.0
30-
- aiohttp>=3.9.0
31-
- click>=8.1.0
32-
- beautifulsoup4>=4.12.0
33-
args: [--ignore-missing-imports]
34-
exclude: ^tests/
18+
# Commented out Sphinx rebuild hook to avoid documentation build warnings
19+
# Uncommatuent if you want docs to rebuild on commit:
20+
# - repo: local
21+
# hooks:
22+
# - id: rebuild-docs
23+
# name: Rebuild Sphinx documentation
24+
# entry: bash -c 'uv run sphinx-build -b html docs docs/_build -q'
25+
# language: system
26+
# pass_filenames: false
27+
# stages: [commit]
28+
# files: '^(python_project_deployment/.*\.py|docs/.*\.rst)$'

‎.scaffold.env.example‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Example configuration file for Python Project Deployment Scaffolder
2+
# Copy this file to .scaffold.env and customize as needed
3+
#
4+
# Configuration precedence: CLI args > Environment variables > .env file > defaults
5+
6+
# ============================================================================
7+
# TIMEOUT SETTINGS (in seconds)
8+
# ============================================================================
9+
10+
# Timeout for git operations (clone, init, commit, etc.)
11+
# Valid range: 1-300 seconds
12+
# Default: 30
13+
#SCAFFOLD_TIMEOUT_GIT=30
14+
15+
# Timeout for package installation (pip, uv sync, etc.)
16+
# Valid range: 60-3600 seconds
17+
# Default: 600
18+
#SCAFFOLD_TIMEOUT_INSTALL=600
19+
20+
# Timeout for running tests (pytest, coverage, etc.)
21+
# Valid range: 30-1800 seconds
22+
# Default: 300
23+
#SCAFFOLD_TIMEOUT_TEST=300
24+
25+
# Timeout for building documentation (sphinx-build)
26+
# Valid range: 30-900 seconds
27+
# Default: 180
28+
#SCAFFOLD_TIMEOUT_DOCS=180
29+
30+
# ============================================================================
31+
# SECURITY SETTINGS
32+
# ============================================================================
33+
34+
# Whether to validate binary executables before use
35+
# Valid values: true, false
36+
# Default: true
37+
#SCAFFOLD_VALIDATE_BINARIES=true
38+
39+
# ============================================================================
40+
# LOGGING SETTINGS
41+
# ============================================================================
42+
43+
# Logging level for scaffolder operations
44+
# Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL
45+
# Default: INFO
46+
#SCAFFOLD_LOG_LEVEL=INFO
47+
48+
# Optional path to log file for persistent logging
49+
# Leave unset to log only to console
50+
# Default: None
51+
#SCAFFOLD_LOG_FILE=/path/to/scaffold.log
52+
53+
# ============================================================================
54+
# USAGE EXAMPLES
55+
# ============================================================================
56+
57+
# Example 1: Increase timeouts for slow network or CI environments
58+
#SCAFFOLD_TIMEOUT_GIT=60
59+
#SCAFFOLD_TIMEOUT_INSTALL=900
60+
#SCAFFOLD_TIMEOUT_TEST=600
61+
62+
# Example 2: Enable debug logging for troubleshooting
63+
#SCAFFOLD_LOG_LEVEL=DEBUG
64+
#SCAFFOLD_LOG_FILE=./scaffold-debug.log
65+
66+
# Example 3: Strict security settings
67+
#SCAFFOLD_VALIDATE_BINARIES=true
68+
69+
# ============================================================================
70+
# NOTES
71+
# ============================================================================
72+
73+
# 1. Environment variables take precedence over .env file values
74+
# 2. CLI arguments take precedence over environment variables
75+
# 3. All SCAFFOLD_* variables are case-insensitive
76+
# 4. Boolean values can be: true/false, yes/no, 1/0
77+
# 5. Invalid values will trigger validation errors with helpful messages

‎Makefile‎

Lines changed: 33 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,20 @@
11
SHELL := /bin/bash
2-
.PHONY: help install sync test lint type format docs precommit clean
2+
.PHONY: help install sync test lint type format docs docs-watch docs-clean docs-rebuild precommit clean
33

44
help:
55
@echo "Available targets:"
6-
@echo " make install # install uv (if missing) and sync dependencies"
7-
@echo " make sync # uv sync --all-extras"
8-
@echo " make test # run tests with coverage"
9-
@echo " make lint # run ruff"
10-
@echo " make type # run mypy"
11-
@echo " make format # format with ruff"
12-
@echo " make docs # build Sphinx docs"
13-
@echo " make precommit # install pre-commit hooks"
14-
@echo " make clean # remove build artifacts"
6+
@echo " make install # install uv (if missing) and sync dependencies"
7+
@echo " make sync # uv sync --all-extras"
8+
@echo " make test # run tests with coverage"
9+
@echo " make lint # run ruff"
10+
@echo " make type # run mypy"
11+
@echo " make format # format with ruff"
12+
@echo " make docs # build Sphinx docs"
13+
@echo " make docs-watch # build docs with auto-reload on changes"
14+
@echo " make docs-clean # remove built docs"
15+
@echo " make docs-rebuild # clean + rebuild docs"
16+
@echo " make precommit # install pre-commit hooks"
17+
@echo " make clean # remove build artifacts"
1518

1619
install:
1720
@command -v uv >/dev/null 2>&1 || \
@@ -25,6 +28,9 @@ sync:
2528
test:
2629
uv run pytest --cov
2730

31+
lock:
32+
uv lock
33+
2834
lint:
2935
uv run ruff check .
3036

@@ -35,7 +41,23 @@ format:
3541
uv run ruff format .
3642

3743
docs:
38-
uv run sphinx-build -b html docs docs/_build
44+
@echo " Building Sphinx documentation..."
45+
@uv run sphinx-build -b html docs docs/_build
46+
@echo " Documentation built at docs/_build/index.html"
47+
48+
docs-watch:
49+
@command -v sphinx-autobuild >/dev/null 2>&1 || \
50+
{ echo "sphinx-autobuild not found. Installing..."; uv add sphinx-autobuild; }
51+
@echo " Starting live documentation server..."
52+
uv run sphinx-autobuild docs docs/_build --open-browser
53+
54+
docs-clean:
55+
@echo " Cleaning documentation build artifacts..."
56+
rm -rf docs/_build docs/_autosummary
57+
@echo " Clean complete"
58+
59+
docs-rebuild: docs-clean docs
60+
@echo " Documentation rebuilt successfully"
3961

4062
precommit:
4163
uv run pre-commit install

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# Python Project Deployment
22

3+
[![CI](https://github.com/Magic-Man-us/PythonProjectDeployment/actions/workflows/ci.yml/badge.svg)](https://github.com/Magic-Man-us/PythonProjectDeployment/actions/workflows/ci.yml)
4+
[![PyPI Version](https://img.shields.io/pypi/v/python-project-deployment.svg)](https://pypi.org/project/python-project-deployment)
5+
[![Python Versions](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13%20|%203.14-blue)](https://www.python.org/downloads/)
6+
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
7+
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
8+
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
9+
[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)
10+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
11+
312
A modern scaffolding tool for creating new Python packages with best practices built-in.
413

514
## Features

‎docs/api.rst‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
API Reference
2+
=============
3+
4+
Core Modules
5+
------------
6+
7+
.. autosummary::
8+
:toctree: generated
9+
:recursive:
10+
11+
python_project_deployment.models
12+
python_project_deployment.scaffolder
13+
python_project_deployment.cli
14+
15+
Main Entry Point
16+
----------------
17+
18+
.. automodule:: python_project_deployment
19+
:members:
20+
:undoc-members:
21+
:show-inheritance:
22+
:no-index:
23+
24+
Models
25+
------
26+
27+
.. automodule:: python_project_deployment.models
28+
:members:
29+
:undoc-members:
30+
:show-inheritance:
31+
32+
Scaffolder
33+
----------
34+
35+
.. automodule:: python_project_deployment.scaffolder
36+
:members:
37+
:undoc-members:
38+
:show-inheritance:
39+
40+
CLI
41+
---
42+
43+
.. automodule:: python_project_deployment.cli
44+
:members:
45+
:undoc-members:
46+
:show-inheritance:

‎docs/conf.py‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,47 @@
1818
"sphinx.ext.autodoc",
1919
"sphinx.ext.napoleon",
2020
"sphinx.ext.viewcode",
21+
"sphinx.ext.intersphinx", # Link to other projects' docs
22+
"sphinx.ext.autosummary", # Generate summary tables
2123
]
2224

25+
# Napoleon settings for Google-style docstrings
26+
napoleon_google_docstring = True
27+
napoleon_numpy_docstring = False
28+
napoleon_include_init_with_doc = True
29+
napoleon_include_private_with_doc = False
30+
napoleon_include_special_with_doc = True
31+
napoleon_use_admonition_for_examples = True
32+
napoleon_use_admonition_for_notes = True
33+
napoleon_use_admonition_for_references = False
34+
napoleon_use_ivar = False
35+
napoleon_use_param = True
36+
napoleon_use_rtype = True
37+
napoleon_type_aliases = None
38+
39+
# Autodoc settings
40+
autodoc_default_options = {
41+
"members": True,
42+
"member-order": "bysource",
43+
"special-members": "__init__",
44+
"undoc-members": True,
45+
"exclude-members": "__weakref__",
46+
"show-inheritance": True,
47+
}
48+
autodoc_typehints = "description"
49+
autodoc_typehints_description_target = "documented"
50+
51+
# Autosummary settings
52+
autosummary_generate = True
53+
54+
# Intersphinx mapping (link to Python docs, etc.)
55+
intersphinx_mapping = {
56+
"python": ("https://docs.python.org/3", None),
57+
"pydantic": ("https://docs.pydantic.dev/latest/", None),
58+
"click": ("https://click.palletsprojects.com/", None),
59+
"jinja2": ("https://jinja.palletsprojects.com/", None),
60+
}
61+
2362
templates_path = ["_templates"]
2463
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
2564

‎docs/generated/python_project_deployment.cli.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
python\_project\_deployment.cli
2+
===============================
3+
4+
.. automodule:: python_project_deployment.cli
5+
6+

‎docs/generated/python_project_deployment.models.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
python\_project\_deployment.models
2+
==================================
3+
4+
.. automodule:: python_project_deployment.models
5+
6+
7+
.. rubric:: Classes
8+
9+
.. autosummary::
10+
11+
ProjectConfig
12+

‎docs/generated/python_project_deployment.scaffolder.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
python\_project\_deployment.scaffolder
2+
======================================
3+
4+
.. automodule:: python_project_deployment.scaffolder
5+
6+
7+
.. rubric:: Classes
8+
9+
.. autosummary::
10+
11+
Scaffolder
12+

0 commit comments

Comments
 (0)