----
+______________________________________________________________________
## Overview
@@ -66,11 +66,11 @@
-Welcome to the {{project_name}} template repository! This template provides a robust foundation for building high-quality, scalable software projects. It includes standard directories, issue templates, CI/CD workflows, and comprehensive placeholder documentation.
+Welcome to the project_name template repository! This template provides a robust foundation for building high-quality, scalable software projects. It includes standard directories, issue templates, CI/CD workflows, and comprehensive placeholder documentation.
-To use this template, simply find and replace all instances of `{{project_name}}` and `{{organization}}` with your actual project details, update the placeholder SVG images in `docs/assets/branding/`, and you are ready to start coding.
+To use this template, simply find and replace all instances of `project_name` and `{{organization}}` with your actual project details, update the placeholder SVG images in `docs/assets/branding/`, and you are ready to start coding.
-### Why Use {{project_name}}?
+### Why Use project_name?
- **Consistency:** Enforces a standardized layout and structure across your organization's repositories.
- **Speed:** Bootstraps your project with pre-configured Actions, badges, and templates so you don't start from scratch.
@@ -78,19 +78,18 @@ To use this template, simply find and replace all instances of `{{project_name}}
### Comparisons
-When evaluating {{project_name}} against other templates, consider the following differences:
-
-| Feature | {{project_name}} Template | Standard GitHub Init | Cookiecutter / Copier |
-| :--- | :--- | :--- | :--- |
-| **Setup Speed** | Very Fast | Fast | Slower (requires CLI tool) |
-| **Visual Assets** | Pre-configured Light/Dark assets | None | Varies |
-| **CI/CD Built-in** | Yes (GitHub Actions) | No | Optional |
-| **Complexity** | Low (Find and Replace) | None | Medium (Jinja templates) |
+When evaluating project_name against other templates, consider the following differences:
+| Feature | project_name Template | Standard GitHub Init | Cookiecutter / Copier |
+| :----------------- | :------------------------------- | :------------------- | :------------------------- |
+| **Setup Speed** | Very Fast | Fast | Slower (requires CLI tool) |
+| **Visual Assets** | Pre-configured Light/Dark assets | None | Varies |
+| **CI/CD Built-in** | Yes (GitHub Actions) | No | Optional |
+| **Complexity** | Low (Find and Replace) | None | Medium (Jinja templates) |
## What's New
-**Welcome to the {{project_name}} Launch!**
+**Welcome to the project_name Launch!**
This project has just been instantiated from the template repository. Keep an eye on this section for future release highlights, new features, and community announcements!
@@ -99,32 +98,32 @@ This project has just been instantiated from the template repository. Keep an ey
## Quick Start
```bash
-
-# e.g., npm install {{project_name}} OR pip install {{project_name}} OR cargo add {{project_name}}
+pip install project_name
```
-For full installation options (from source, Docker, platform-specific notes) and step-by-step onboarding, see the **[Getting Started guide](https://{{organization}}.github.io/{{project_name}}/getting-started/)**.
+For full installation options (from source, Docker, platform-specific notes) and step-by-step onboarding, see the **[Getting Started guide](https://%7B%7Borganization%7D%7D.github.io/%7B%7Bproject_name%7D%7D/getting-started/)**.
## Core Concepts
-
+This project is built using modern Python tooling, ensuring a stable and typed foundation. It utilizes Pydantic for data validation and Ruff/Mypy for code quality.
### Component Architecture
The template is organized into several key areas:
+
- `docs/`: Stores your documentation and branding assets.
- `src/` (or your primary package directory): The core application logic.
- `tests/`: Automated tests to ensure code quality.
## Advanced Usage
-
+Please check the [`docs/examples/`](docs/examples/) directory for advanced examples and configurations.
## General
### Contributing
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details. For development setup, check out [DEVELOPING.md](DEVELOPING.md).
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details. For development setup, check out [DEVELOPING.md](DEVELOPING.md).
Please ensure you follow our [Code of Conduct](CODE_OF_CONDUCT.md) in all interactions.
### Support and Security
@@ -148,12 +147,12 @@ This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE
If you use this template or the resulting software in your research, please cite it using the following BibTeX entry:
```bibtex
-@software{{{project_name}},
+@software{project_name,
author = {{{organization}}},
- title = {{{project_name}}},
+ title = {project_name},
version = {{{version}}},
month = {{{month}}},
year = {2026},
- url = {https://github.com/{{organization}}/{{project_name}}}
+ url = {https://github.com/{{organization}}/project_name}
}
```
diff --git a/SECURITY.md b/SECURITY.md
index a999843..cca8520 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,15 +1,15 @@
-# Security Policy for `{{project_name}}`
+# Security Policy for `project_name`
-We take the security of `{{project_name}}` seriously. This document outlines our security policies, supported versions, and how to responsibly disclose a vulnerability.
+We take the security of `project_name` seriously. This document outlines our security policies, supported versions, and how to responsibly disclose a vulnerability.
## Supported Versions
-Please check the table below for the versions of `{{project_name}}` that are currently being supported with security updates.
+Please check the table below for the versions of `project_name` that are currently being supported with security updates.
-| Version | Supported |
-| :--- | :--- |
-| `{{current_major_version}}.x` | :white_check_mark: |
-| `< {{current_major_version}}.0` | :x: |
+| Version | Supported |
+| :------------------------------ | :----------------- |
+| `{{current_major_version}}.x` | :white_check_mark: |
+| `< {{current_major_version}}.0` | :x: |
*(Note: Replace the table contents with your actual versioning scheme once released.)*
@@ -20,37 +20,40 @@ Please check the table below for the versions of `{{project_name}}` that are cur
If you discover a security vulnerability, please bring it to our attention right away using one of the following methods:
-1. **GitHub Security Advisories (Preferred):** Use the "Report a vulnerability" button on the **[Security tab](https://github.com/{{organization}}/{{project_name}}/security/advisories)** of this repository.
-2. **Email:** Send your report directly to **[INSERT EMAIL ADDRESS OR SECURITY CONTACT]**. *(Optional: Encrypt your email using our PGP key: [INSERT PGP KEY LINK/FINGERPRINT])*
+1. **GitHub Security Advisories (Preferred):** Use the "Report a vulnerability" button on the **[Security tab](https://github.com/%7B%7Borganization%7D%7D/%7B%7Bproject_name%7D%7D/security/advisories)** of this repository.
+1. **Email:** Send your report directly to **[INSERT EMAIL ADDRESS OR SECURITY CONTACT]**. *(Optional: Encrypt your email using our PGP key: [INSERT PGP KEY LINK/FINGERPRINT])*
### What to Include in Your Report
To help us resolve the issue quickly, please include the following information:
+
- **Type of vulnerability** (e.g., XSS, SQLi, RCE, authorization bypass).
- **Detailed description** of the vulnerability and its potential impact.
- **Step-by-step instructions** to reproduce the issue.
- **Proof of Concept (PoC)** code or screenshots, if available.
-- **Environment details** (e.g., version of `{{project_name}}`, OS, relevant configurations).
+- **Environment details** (e.g., version of `project_name`, OS, relevant configurations).
## Triage and Resolution Process
We will handle your report with strict confidentiality. Our process is as follows:
1. **Acknowledgment:** We will respond to your report as soon as possible, usually within **[INSERT NUMBER, e.g., 48] hours**.
-2. **Triage:** We will investigate the issue and determine its validity and severity. We may contact you for further clarification.
-3. **Fix:** If the vulnerability is verified, we will develop and test a patch.
-4. **Disclosure:** We will coordinate with you to publicly disclose the vulnerability once a fix is released. We will publicly acknowledge your responsible disclosure, if you wish.
+1. **Triage:** We will investigate the issue and determine its validity and severity. We may contact you for further clarification.
+1. **Fix:** If the vulnerability is verified, we will develop and test a patch.
+1. **Disclosure:** We will coordinate with you to publicly disclose the vulnerability once a fix is released. We will publicly acknowledge your responsible disclosure, if you wish.
## Scope
**In Scope:**
-- Vulnerabilities within the core `{{project_name}}` codebase.
+
+- Vulnerabilities within the core `project_name` codebase.
- Security issues in our default configurations.
**Out of Scope:**
+
- Volumetric Denial of Service (DoS) attacks.
- Theoretical issues without a reproducible PoC.
-- Vulnerabilities in third-party dependencies that are not exploitable through `{{project_name}}`.
+- Vulnerabilities in third-party dependencies that are not exploitable through `project_name`.
- Missing security headers or best practices that do not lead to a direct exploit.
*(Note: We currently **[do/do not]** operate a bug bounty program. Disclosures are greatly appreciated but are not eligible for financial rewards at this time.)*
diff --git a/SUPPORT.md b/SUPPORT.md
index dd8714d..532325f 100644
--- a/SUPPORT.md
+++ b/SUPPORT.md
@@ -1,6 +1,6 @@
-# Support for `{{project_name}}`
+# Support for `project_name`
-We are excited to have you use `{{project_name}}`! If you need help, please follow these guidelines to ensure you get support quickly and efficiently.
+We are excited to have you use `project_name`! If you need help, please follow these guidelines to ensure you get support quickly and efficiently.
## Security Vulnerabilities
@@ -13,19 +13,19 @@ If you have found a security vulnerability, please refer to our [Security Policy
Before reaching out, we recommend checking the following resources. Many common questions and issues are already covered there.
-- **[Official Documentation](https://{{organization}}.github.io/{{project_name}}):** Comprehensive guides, tutorials, and API references.
-- **[GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues):** Search existing issues to see if someone else has already reported your problem or requested your feature. Feel free to add a "+1" reaction to existing issues to show your interest.
-- **[GitHub Discussions](https://github.com/{{organization}}/{{project_name}}/discussions):** Search our discussions for Q&A, general advice, and community knowledge.
+- **[Official Documentation](https://%7B%7Borganization%7D%7D.github.io/%7B%7Bproject_name%7D%7D):** Comprehensive guides, tutorials, and API references.
+- **[GitHub Issues](https://github.com/%7B%7Borganization%7D%7D/%7B%7Bproject_name%7D%7D/issues):** Search existing issues to see if someone else has already reported your problem or requested your feature. Feel free to add a "+1" reaction to existing issues to show your interest.
+- **[GitHub Discussions](https://github.com/%7B%7Borganization%7D%7D/%7B%7Bproject_name%7D%7D/discussions):** Search our discussions for Q&A, general advice, and community knowledge.
## Opening a New Issue
If you cannot find an answer in the documentation or existing issues, please open a new issue. To help us resolve your issue faster, please choose the correct venue:
-| Issue Type | Venue | Description |
-| :--- | :--- | :--- |
-| **Bug Report** | [GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues/new) | Use the "Bug Report" template. Provide reproducible steps, environment details, and relevant logs. |
-| **Feature Request** | [GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues/new) | Use the "Feature Request" template. Clearly describe your use case and the problem the feature would solve. |
-| **Q&A / General Help** | [GitHub Discussions](https://github.com/{{organization}}/{{project_name}}/discussions/new) | Start a discussion for questions about how to use `{{project_name}}`, architecture queries, or advice. |
+| Issue Type | Venue | Description |
+| :--------------------- | :--------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
+| **Bug Report** | [GitHub Issues](https://github.com/%7B%7Borganization%7D%7D/%7B%7Bproject_name%7D%7D/issues/new) | Use the "Bug Report" template. Provide reproducible steps, environment details, and relevant logs. |
+| **Feature Request** | [GitHub Issues](https://github.com/%7B%7Borganization%7D%7D/%7B%7Bproject_name%7D%7D/issues/new) | Use the "Feature Request" template. Clearly describe your use case and the problem the feature would solve. |
+| **Q&A / General Help** | [GitHub Discussions](https://github.com/%7B%7Borganization%7D%7D/%7B%7Bproject_name%7D%7D/discussions/new) | Start a discussion for questions about how to use `project_name`, architecture queries, or advice. |
## Community Channels
@@ -38,4 +38,5 @@ Join our community to chat with other users, contributors, and the core maintain
## Commercial Support
-At this time, there is no official commercial support available for `{{project_name}}`. Support is provided on a best-effort basis by the open-source community and maintainers.
+
+At this time, there is no official commercial support available for `project_name`. Support is provided on a best-effort basis by the open-source community and maintainers.
diff --git a/docker-compose.yml b/docker-compose.yml
index da6a338..ff79821 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,8 +1,8 @@
+---
# ---------------------------------------------------------
-# {{project_name}} Docker Compose
+# project_name Docker Compose
# Licensed under the Apache License, Version 2.0
# ---------------------------------------------------------
-
services:
app:
build:
@@ -15,9 +15,11 @@ services:
environment:
- APP_ENV=${APP_ENV:-development}
- APP_DEBUG=${APP_DEBUG:-true}
- # Replace this with your language-specific live-reload or run command
- # Examples: ["npm", "run", "dev"], ["make", "run"], ["cargo", "run"]
- command: ["/bin/sh", "-c", "echo 'Please define a command in docker-compose.yml!'; exit 1"]
+ # Standard Python development command
+ command:
+ - "python"
+ - "-m"
+ - "project_name"
# Standard Database Profile
# Use `docker-compose --profile db up` to start this service
@@ -30,9 +32,8 @@ services:
environment:
POSTGRES_USER: ${DB_USER:-admin}
POSTGRES_PASSWORD: ${DB_PASSWORD:-secret}
- POSTGRES_DB: ${DB_NAME:-{{project_name}}_dev}
+ POSTGRES_DB: ${DB_NAME:-project_name_dev}
volumes:
- db_data:/var/lib/postgresql/data
-
volumes:
db_data:
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index 68d078c..0000000
--- a/docs/README.md
+++ /dev/null
@@ -1,172 +0,0 @@
-# Documentation
-
-This directory contains the source files for the `{{project_name}}` documentation site, built with [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
-
-## Directory Structure
-
-```
-docs/
-├── assets/ # Branding assets (logos, diagrams, favicons)
-├── community/ # Contributing, Code of Conduct, Security, Support
-├── examples/ # Runnable code examples and demos
-├── getting-started/ # Installation, quick start, and workflow guides
-├── guides/ # Task-oriented how-to guides
-├── reference/ # API reference and configuration schema
-├── scripts/ # Custom JavaScript for the docs site (extra.js)
-├── stylesheets/ # Custom CSS for the docs site (extra.css)
-├── index.md # Docs home page (hero landing page)
-└── README.md # This file
-```
-
-The MkDocs configuration lives at the repository root: [`mkdocs.yml`](../mkdocs.yml).
-
-
-## Prerequisites
-
-- **Python 3.9+** — Required to run MkDocs and its plugins.
-- **pip** — For installing documentation dependencies.
-
-All documentation dependencies are listed in `docs/requirements.txt`. Install them with:
-
-```bash
-pip install -r docs/requirements.txt
-```
-
-> **Tip:** See [DEVELOPING.md](../DEVELOPING.md) for the full local setup guide. Even if your main project is not in Python, the documentation is built with MkDocs and requires a Python environment to build locally.
-
-
-
-## Local Development
-
-### Serve the Docs Locally
-
-Start the live-reloading development server from the **repository root**:
-
-```bash
-mkdocs serve
-```
-
-The site will be available at [http://127.0.0.1:8000](http://127.0.0.1:8000). Any change you save to a source file is reflected immediately in the browser — no manual refresh needed.
-
-### Specify a Custom Host or Port
-
-```bash
-mkdocs serve --dev-addr 0.0.0.0:8080
-```
-
-### Template Variables
-
-All `{{ variable }}` references in the docs (e.g. `{{ project_name }}`, `{{ org_name }}`) are driven by the `extra:` block in [`mkdocs.yml`](../mkdocs.yml). Update those values once and the change propagates across the entire site:
-
-```yaml
-# mkdocs.yml
-extra:
- project_name: "my-project"
- org_name: "my-org"
- # ... other variables
-```
-
-
-## Building the Docs
-
-Produce a static build of the site in the `site/` directory:
-
-```bash
-mkdocs build
-```
-
-> The `site/` directory is intentionally excluded from version control via `.gitignore`. Do **not** commit it manually.
-
-To perform a clean build (removes the previous `site/` output first):
-
-```bash
-mkdocs build --clean
-```
-
-Validate that all internal links resolve correctly:
-
-```bash
-mkdocs build --strict
-```
-
-The `--strict` flag is recommended before opening a pull request or cutting a release to catch broken links early.
-
-
-## Publishing the Docs
-
-### Automated Publishing (Recommended)
-
-Documentation is published automatically to **GitHub Pages** on every merge to `main` (or on a tagged release, depending on your workflow configuration). No manual steps are required — simply merge your changes and the CI/CD pipeline handles the rest.
-
-See the relevant workflow file in [`.github/workflows/`](../.github/workflows/) for the exact trigger and deployment steps.
-
-### Manual Publishing
-
-If you need to publish outside of the normal CI/CD cycle, run the following from the **repository root**:
-
-```bash
-mkdocs gh-deploy --force
-```
-
-This command builds the static site and force-pushes it to the `gh-pages` branch of your repository, which GitHub Pages then serves automatically.
-
-> **Note:** Manual deploys require you to have write access to the repository and a configured `git` identity (`user.name` and `user.email`).
-
-#### Dry-run First
-
-To preview what `gh-deploy` would do without actually pushing:
-
-```bash
-mkdocs gh-deploy --dry-run
-```
-
-
-## Adding and Editing Pages
-
-1. **Create a new `.md` file** in the appropriate subdirectory (e.g., `guides/my-new-guide.md`).
-2. **Register it in the nav** by adding an entry to the `nav:` block in [`mkdocs.yml`](../mkdocs.yml).
-3. **Preview locally** with `mkdocs serve` before opening a pull request.
-
-### Page Metadata
-
-Every page should include a top-level `# Heading` that matches its nav label. Optionally, add MkDocs front matter for advanced layout control:
-
-```yaml
----
-hide:
- - toc # Hide the table of contents
- - navigation # Hide the left-hand nav
----
-```
-
-### Admonitions
-
-This site uses [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/) and MkDocs Material admonitions. Use them liberally:
-
-```markdown
-!!! note
- This is an informational note.
-
-!!! warning
- This is a warning.
-```
-
-
-## Common Troubleshooting
-
-| Symptom | Likely Cause | Fix |
-| :--- | :--- | :--- |
-| `mkdocs: command not found` | Dependencies not installed | `pip install mkdocs mkdocs-material mkdocs-macros-plugin pymdown-extensions` |
-| `{{ variable }}` renders literally | `mkdocs-macros-plugin` missing or misconfigured | Confirm `macros` is listed under `plugins:` in `mkdocs.yml` |
-| Broken links on `--strict` build | Missing or misnamed file in `nav:` | Verify file path and `nav:` registration in `mkdocs.yml` |
-| Styles missing in local preview | Custom CSS path wrong | Confirm `extra_css` path in `mkdocs.yml` matches `docs/stylesheets/extra.css` |
-| `gh-deploy` push rejected | Stale `gh-pages` branch | Use `mkdocs gh-deploy --force` or delete and re-create the `gh-pages` branch |
-
-
-## Related Resources
-
-- [MkDocs Documentation](https://www.mkdocs.org/)
-- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
-- [MkDocs Macros Plugin](https://mkdocs-macros-plugin.readthedocs.io/)
-- [PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/)
-- [GitHub Pages — Publishing Source](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)
diff --git a/docs/community/agents.md b/docs/community/agents.md
index 97ecbc2..ece8699 100644
--- a/docs/community/agents.md
+++ b/docs/community/agents.md
@@ -1 +1,5 @@
---8<-- "AGENTS.md"
+
+
+--8\<-- "AGENTS.md"
+
+
diff --git a/docs/community/code-of-conduct.md b/docs/community/code-of-conduct.md
index 01f2ea2..2c30ec8 100644
--- a/docs/community/code-of-conduct.md
+++ b/docs/community/code-of-conduct.md
@@ -1 +1,5 @@
---8<-- "CODE_OF_CONDUCT.md"
+
+
+--8\<-- "CODE_OF_CONDUCT.md"
+
+
diff --git a/docs/community/contributing.md b/docs/community/contributing.md
index ea38c9b..adcb4b8 100644
--- a/docs/community/contributing.md
+++ b/docs/community/contributing.md
@@ -1 +1,5 @@
---8<-- "CONTRIBUTING.md"
+
+
+--8\<-- "CONTRIBUTING.md"
+
+
diff --git a/docs/community/developing.md b/docs/community/developing.md
index 6e6ec19..6cb61e8 100644
--- a/docs/community/developing.md
+++ b/docs/community/developing.md
@@ -1 +1,5 @@
---8<-- "DEVELOPING.md"
+
+
+--8\<-- "DEVELOPING.md"
+
+
diff --git a/docs/community/index.md b/docs/community/index.md
index 7f3e639..bf1ee89 100644
--- a/docs/community/index.md
+++ b/docs/community/index.md
@@ -2,60 +2,58 @@
`{{ project_name }}` is an open-source project and we welcome participation from everyone. This section contains all the resources you need to get involved, stay informed, and interact with the community.
-
## Get Involved
-- :material-source-pull: **Contributing**
+- :material-source-pull: **Contributing**
- ---
+ ______________________________________________________________________
- How to report bugs, suggest features, and submit pull requests.
+ How to report bugs, suggest features, and submit pull requests.
- [:octicons-arrow-right-24: Contributing Guide](contributing.md)
+ [:octicons-arrow-right-24: Contributing Guide](contributing.md)
-- :material-wrench-outline: **Developer Setup**
+- :material-wrench-outline: **Developer Setup**
- ---
+ ______________________________________________________________________
- Full environment setup guide for contributors — Docker, local dev,
- testing, and code quality standards.
+ Full environment setup guide for contributors — Docker, local dev,
+ testing, and code quality standards.
- [:octicons-arrow-right-24: Developer Setup](developing.md)
+ [:octicons-arrow-right-24: Developer Setup](developing.md)
-- :material-handshake-outline: **Code of Conduct**
+- :material-handshake-outline: **Code of Conduct**
- ---
+ ______________________________________________________________________
- Our community standards and the guidelines we expect all participants to follow.
+ Our community standards and the guidelines we expect all participants to follow.
- [:octicons-arrow-right-24: Code of Conduct](code-of-conduct.md)
+ [:octicons-arrow-right-24: Code of Conduct](code-of-conduct.md)
-- :material-shield-lock-outline: **Security Policy**
+- :material-shield-lock-outline: **Security Policy**
- ---
+ ______________________________________________________________________
- How to responsibly disclose security vulnerabilities and our triage process.
+ How to responsibly disclose security vulnerabilities and our triage process.
- [:octicons-arrow-right-24: Security Policy](security.md)
+ [:octicons-arrow-right-24: Security Policy](security.md)
-- :material-lifebuoy: **Support**
+- :material-lifebuoy: **Support**
- ---
+ ______________________________________________________________________
- Where to ask questions, report issues, and find help.
+ Where to ask questions, report issues, and find help.
- [:octicons-arrow-right-24: Support](support.md)
+ [:octicons-arrow-right-24: Support](support.md)
-
## Community Channels
-| Channel | Purpose |
-| :--- | :--- |
-| [GitHub Issues](https://github.com/{{ org_name }}/{{ project_name }}/issues) | Bug reports and feature requests |
-| [GitHub Discussions](https://github.com/{{ org_name }}/{{ project_name }}/discussions) | Q&A, ideas, and general community conversation |
-| [Slack]({{ slack_url }}) | Real-time chat with the team and community |
-| [Blog]({{ blog_url }}) | Project updates, tutorials, and announcements |
+| Channel | Purpose |
+| :--------------------------------------------------------------------------------------- | :--------------------------------------------- |
+| \[GitHub Issues\](https://github.com/{{ org_name }}/{{ project_name }}/issues) | Bug reports and feature requests |
+| \[GitHub Discussions\](https://github.com/{{ org_name }}/{{ project_name }}/discussions) | Q&A, ideas, and general community conversation |
+| \[Slack\]({{ slack_url }}) | Real-time chat with the team and community |
+| \[Blog\]({{ blog_url }}) | Project updates, tutorials, and announcements |
diff --git a/docs/community/security.md b/docs/community/security.md
index a8ada70..90c632e 100644
--- a/docs/community/security.md
+++ b/docs/community/security.md
@@ -1 +1,5 @@
---8<-- "SECURITY.md"
+
+
+--8\<-- "SECURITY.md"
+
+
diff --git a/docs/community/support.md b/docs/community/support.md
index 05fc079..1374725 100644
--- a/docs/community/support.md
+++ b/docs/community/support.md
@@ -1 +1,5 @@
---8<-- "SUPPORT.md"
+
+
+--8\<-- "SUPPORT.md"
+
+
diff --git a/docs/examples/index.md b/docs/examples/index.md
index 9bcbff5..19f7b78 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -5,49 +5,51 @@ This section contains runnable code examples that demonstrate real-world usage o
> [!NOTE]
> All examples assume you have completed [Installation](../getting-started/installation.md). Replace `YOUR_KEY` and other placeholder values with your own credentials before running.
-
## Example Categories
-- :material-rocket-launch-outline: **Basic Examples**
+- :material-rocket-launch-outline: **Basic Examples**
- ---
+ ______________________________________________________________________
- Simple, minimal examples that demonstrate the core API with no extra setup required. The best place to start.
+ Simple, minimal examples that demonstrate the core API with no extra setup required. The best place to start.
-
- *Coming soon.*
+
-- :material-tune-variant: **Advanced Examples**
+ *Coming soon.*
- ---
+- :material-tune-variant: **Advanced Examples**
- Examples that demonstrate more complex patterns, custom configurations, and production-grade usage.
+ ______________________________________________________________________
-
- *Coming soon.*
+ Examples that demonstrate more complex patterns, custom configurations, and production-grade usage.
-- :material-console: **CLI Examples**
+
- ---
+ *Coming soon.*
- Examples using the `{{ project_name }}` command-line interface, including scripting and automation patterns.
+- :material-console: **CLI Examples**
-
- *Coming soon.*
+ ______________________________________________________________________
-- :material-docker: **Docker Examples**
+ Examples using the `{{ project_name }}` command-line interface, including scripting and automation patterns.
- ---
+
- Containerised usage examples, including Docker Compose configurations for common deployment scenarios.
+ *Coming soon.*
-
- *Coming soon.*
+- :material-docker: **Docker Examples**
-
+ ______________________________________________________________________
+
+ Containerised usage examples, including Docker Compose configurations for common deployment scenarios.
+
+
+ *Coming soon.*
+
+
!!! tip "Contributing an Example"
- Have a useful snippet or pattern to share? See the [Contributing Guide](../community/contributing.md) to learn how to add a new example to this section.
+Have a useful snippet or pattern to share? See the [Contributing Guide](../community/contributing.md) to learn how to add a new example to this section.
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
index 045d997..af90a35 100644
--- a/docs/getting-started/index.md
+++ b/docs/getting-started/index.md
@@ -4,35 +4,34 @@ Welcome to `{{ project_name }}`! This section walks you through everything you n
Follow the pages in order for the best experience, or jump directly to the section you need.
-
## In This Section
-- :material-download-outline: **Installation**
+- :material-download-outline: **Installation**
- ---
+ ______________________________________________________________________
- Install `{{ project_name }}` via pip, from source, or using Docker.
- Includes platform-specific notes and verification steps.
+ Install `{{ project_name }}` via pip, from source, or using Docker.
+ Includes platform-specific notes and verification steps.
- [:octicons-arrow-right-24: Installation Guide](installation.md)
+ [:octicons-arrow-right-24: Installation Guide](installation.md)
-- :material-play-circle-outline: **Quick Start**
+- :material-play-circle-outline: **Quick Start**
- ---
+ ______________________________________________________________________
- Your first 5 minutes with `{{ project_name }}`. Initialize, run a command,
- and see results — fast.
+ Your first 5 minutes with `{{ project_name }}`. Initialize, run a command,
+ and see results — fast.
- [:octicons-arrow-right-24: Quick Start](quickstart.md)
+ [:octicons-arrow-right-24: Quick Start](quickstart.md)
-- :material-transit-connection-variant: **Workflows**
+- :material-transit-connection-variant: **Workflows**
- ---
+ ______________________________________________________________________
- End-to-end walkthroughs for the most common user stories and usage patterns.
+ End-to-end walkthroughs for the most common user stories and usage patterns.
- [:octicons-arrow-right-24: Workflows](workflows.md)
+ [:octicons-arrow-right-24: Workflows](workflows.md)
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 22dcac3..a929f7b 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -2,26 +2,23 @@
This page covers all supported installation methods for `{{ project_name }}`.
-
## Requirements
Before installing, ensure your system meets the following prerequisites:
-| Requirement | Minimum Version | Notes |
-| :--- | :--- | :--- |
-| **Language** | | Required for all installation methods |
-| **Package Manager**| | Required for dependencies |
-| **Git** | 2.x | Required for source installs |
-| **Docker** | 24.x | Optional — for containerized installs |
-
+| Requirement | Minimum Version | Notes |
+| :------------------ | :-------------- | :------------------------------------ |
+| **Python** | 3.10+ | Required for all installation methods |
+| **Package Manager** | pip or Hatch | Required for dependencies |
+| **Git** | 2.x | Required for source installs |
+| **Docker** | 24.x | Optional — for containerized installs |
## Standard Installation
The recommended way to install `{{ project_name }}` for most users:
```bash
-
-# e.g., npm install {{project_name}} OR pip install {{project_name}} OR cargo add {{project_name}}
+pip install project_name
```
### Verify the Installation
@@ -38,7 +35,6 @@ You should see output similar to:
{{ project_name }} 0.1.0
```
-
## Install from Source
To install the latest unreleased code directly from the repository:
@@ -48,14 +44,17 @@ git clone https://github.com/{{ org_name }}/{{ project_name }}.git
cd {{ project_name }}
# Install dependencies for development
-
-# e.g., npm ci OR pip install -e ".[dev]" OR cargo build
+# If you are using hatch (recommended):
+pipx install hatch
+hatch shell
+
+# Or using pip directly:
+pip install -e .
```
> [!TIP]
> This is the recommended setup for contributors looking to make changes to the source code.
-
## Docker Installation
A pre-built Docker image is available for containerized environments:
@@ -70,47 +69,48 @@ docker run --rm ghcr.io/{{ org_name }}/{{ project_name }}:latest {{ project_name
For a persistent, volume-mounted setup using Docker Compose, see the `docker-compose.yml` in the root of the repository.
-
## Platform-Specific Notes
=== "macOS"
-
+```
+Python and `pip` or `hatch` work seamlessly on macOS. We recommend using `brew install python` if you need a base Python environment.
+```
=== "Linux"
-
+```
+Use your distribution's package manager to install Python 3.10+ (e.g., `sudo apt install python3`).
+```
=== "Windows"
-
-
+```
+Ensure Python is added to your PATH during the Windows installer setup.
+```
## Upgrading
To upgrade an existing installation to the latest release:
```bash
-
+pip install --upgrade project_name
```
-
## Uninstalling
```bash
-
+pip uninstall project_name
```
-
## Troubleshooting
-| Problem | Solution |
-| :--- | :--- |
-| `command not found: {{ project_name }}` | Ensure the binaries directory is on your `$PATH`. |
-| Import errors after install | Ensure you have the latest version installed. |
-| Version conflicts | Isolate your dependencies using your language's recommended tool. |
+| Problem | Solution |
+| :-------------------------------------- | :---------------------------------------------------------------- |
+| `command not found: {{ project_name }}` | Ensure the binaries directory is on your `$PATH`. |
+| Import errors after install | Ensure you have the latest version installed. |
+| Version conflicts | Isolate your dependencies using your language's recommended tool. |
If you continue to experience issues, please visit our [Support page](../community/support.md).
-
-**Next:** [Quick Start →](quickstart.md)
+**Next:** [Quick Start →](quickstart.md)
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 490f2ce..c602607 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -5,17 +5,16 @@ This guide gets you from a fresh installation to running your first command in u
> [!NOTE]
> Make sure you have completed [Installation](installation.md) before continuing.
-
## Step 1 — Initialize Your Environment
If you haven't already, set up your project and install `{{ project_name }}`:
```bash
-
-# e.g., npm init && npm install {{project_name}}
+python -m venv .venv
+source .venv/bin/activate
+pip install project_name
```
-
## Step 2 — Verify the Install
```bash
@@ -28,20 +27,17 @@ Expected output:
{{ project_name }} 0.1.0
```
-
## Step 3 — Run Your First Command
-```text
-
-// e.g., Javascript, Python, Go, Rust
-import { Client } from '{{ project_name }}';
+```python
+from project_name import Client
-// Initialize the client
-const client = new Client({ apiKey: "YOUR_KEY" });
+# Initialize the client
+client = Client(api_key="YOUR_KEY")
-// Run a core action
-const result = await client.runAction("hello_world");
-console.log(result);
+# Run a core action
+result = client.run_action("hello_world")
+print(result)
```
Expected output:
@@ -54,7 +50,6 @@ Expected output:
> [!TIP]
> Replace `"YOUR_KEY"` with your actual API key or credentials. See the [Reference](../reference/index.md) for all available client configuration options.
-
## Step 4 — Explore Further
Now that your first command works, explore what `{{ project_name }}` can do:
@@ -64,5 +59,4 @@ Now that your first command works, explore what `{{ project_name }}` can do:
- **[Reference](../reference/index.md)** — Full API and CLI documentation
- **[Examples](../examples/index.md)** — Runnable code examples
-
-**Next:** [Workflows →](workflows.md)
+**Next:** [Workflows →](workflows.md)
diff --git a/docs/getting-started/workflows.md b/docs/getting-started/workflows.md
index 9fd3c41..653cc23 100644
--- a/docs/getting-started/workflows.md
+++ b/docs/getting-started/workflows.md
@@ -5,7 +5,6 @@ This page walks through the most common end-to-end usage patterns for `{{ projec
> [!NOTE]
> These are placeholder workflows. Replace each section with the real workflows that users of your project will follow.
-
## Workflow 1 — Basic Usage
**Goal:** Perform the most common, standard operation with `{{ project_name }}`.
@@ -14,28 +13,28 @@ This page walks through the most common end-to-end usage patterns for `{{ projec
1. **Initialize the client**
- ```text
-
- ```
+```python
+from {{ project_name }} import Client
+client = Client(api_key="YOUR_KEY")
+```
2. **Configure your inputs**
- ```text
-
- ```
+```python
+config = {"mode": "fast", "retries": 3}
+```
3. **Execute the action**
- ```text
-
- ```
+```python
+result = client.run_action("hello_world", config=config)
+```
4. **Handle the output**
- ```text
-
- ```
-
+```python
+print(f"Success: {result}")
+```
## Workflow 2 — Docker-Based Execution
@@ -45,26 +44,25 @@ This page walks through the most common end-to-end usage patterns for `{{ projec
1. **Pull the image**
- ```bash
- docker pull ghcr.io/{{ org_name }}/{{ project_name }}:latest
- ```
+ ```bash
+ docker pull ghcr.io/{{ org_name }}/{{ project_name }}:latest
+ ```
-2. **Run with environment variables**
+1. **Run with environment variables**
- ```bash
- docker run --rm \
- -e API_KEY="YOUR_KEY" \
- -v $(pwd)/output:/app/output \
- ghcr.io/{{ org_name }}/{{ project_name }}:latest \
- {{ project_name }} run --output /app/output
- ```
+ ```bash
+ docker run --rm \
+ -e API_KEY="YOUR_KEY" \
+ -v $(pwd)/output:/app/output \
+ ghcr.io/{{ org_name }}/{{ project_name }}:latest \
+ {{ project_name }} run --output /app/output
+ ```
-3. **Inspect the output**
-
- ```bash
- ls ./output/
- ```
+1. **Inspect the output**
+ ```bash
+ ls ./output/
+ ```
## Workflow 3 — CI/CD Integration
@@ -83,11 +81,13 @@ jobs:
- uses: actions/checkout@v4
- name: Set up environment
- #
+ uses: actions/setup-python@v5
+ with:
+ python-version: "3.10"
- name: Install {{ project_name }}
run: |
- #
+ pip install .
- name: Run action
env:
@@ -95,5 +95,4 @@ jobs:
run: {{ project_name }} run --config config.yaml
```
-
**Need more?** See the [Guides](../guides/index.md) section for in-depth task-specific documentation or browse the [Examples](../examples/index.md) for runnable code.
diff --git a/docs/guides/index.md b/docs/guides/index.md
index a891c37..59a5e92 100644
--- a/docs/guides/index.md
+++ b/docs/guides/index.md
@@ -2,49 +2,51 @@
This section contains task-oriented how-to guides for `{{ project_name }}`. Unlike the [Getting Started](../getting-started/index.md) section, which is structured as a linear onboarding path, these guides are standalone — jump to whichever one is relevant to your current task.
-
## Available Guides
-- :material-cog-outline: **Configuration**
+- :material-cog-outline: **Configuration**
- ---
+ ______________________________________________________________________
- A deep dive into all configuration options, file formats, and environment variables supported by `{{ project_name }}`.
+ A deep dive into all configuration options, file formats, and environment variables supported by `{{ project_name }}`.
-
- *Coming soon.*
+
-- :material-puzzle-outline: **Integrations**
+ *Coming soon.*
- ---
+- :material-puzzle-outline: **Integrations**
- Step-by-step instructions for integrating `{{ project_name }}` with third-party tools, platforms, and services.
+ ______________________________________________________________________
-
- *Coming soon.*
+ Step-by-step instructions for integrating `{{ project_name }}` with third-party tools, platforms, and services.
-- :material-shield-half-full: **Authentication & Security**
+
- ---
+ *Coming soon.*
- How to configure authentication, manage secrets, and follow security best practices when deploying `{{ project_name }}`.
+- :material-shield-half-full: **Authentication & Security**
-
- *Coming soon.*
+ ______________________________________________________________________
-- :material-swap-horizontal: **Migration**
+ How to configure authentication, manage secrets, and follow security best practices when deploying `{{ project_name }}`.
- ---
+
- Guides for upgrading between major versions and migrating from other tools to `{{ project_name }}`.
+ *Coming soon.*
-
- *Coming soon.*
+- :material-swap-horizontal: **Migration**
-
+ ______________________________________________________________________
+
+ Guides for upgrading between major versions and migrating from other tools to `{{ project_name }}`.
+
+
+ *Coming soon.*
+
+
!!! tip "Contributing a Guide"
- Have a workflow or pattern worth documenting? See the [Contributing Guide](../community/contributing.md) to learn how to add a new guide to this section.
+Have a workflow or pattern worth documenting? See the [Contributing Guide](../community/contributing.md) to learn how to add a new guide to this section.
diff --git a/docs/index.md b/docs/index.md
index 8f5f5ef..24e5896 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -13,81 +13,85 @@ hide:
A production-ready Apache 2.0 template that gives you a fully structured, documented, and CI/CD-enabled starting point — so you can focus on building, not scaffolding.
+
+
[Get Started](getting-started/index.md){ .md-button .md-button--primary }
-[View on GitHub](https://github.com/{{ org_name }}/{{ project_name }}){ .md-button }
+\[View on GitHub\](https://github.com/{{ org_name }}/{{ project_name }}){ .md-button }
+
+
-
## What's Included
-- :material-rocket-launch-outline: **Getting Started**
+- :material-rocket-launch-outline: **Getting Started**
- ---
+ ______________________________________________________________________
- Installation guide, quick start tutorial, and common workflow walkthroughs.
+ Installation guide, quick start tutorial, and common workflow walkthroughs.
- [:octicons-arrow-right-24: Get Started](getting-started/index.md)
+ [:octicons-arrow-right-24: Get Started](getting-started/index.md)
-- :material-book-open-outline: **Guides**
+- :material-book-open-outline: **Guides**
- ---
+ ______________________________________________________________________
- Step-by-step guides for common tasks, integrations, and configuration patterns.
+ Step-by-step guides for common tasks, integrations, and configuration patterns.
- [:octicons-arrow-right-24: Browse Guides](guides/index.md)
+ [:octicons-arrow-right-24: Browse Guides](guides/index.md)
-- :material-code-braces: **Examples**
+- :material-code-braces: **Examples**
- ---
+ ______________________________________________________________________
- Runnable code examples that demonstrate real-world usage of `{{ project_name }}`.
+ Runnable code examples that demonstrate real-world usage of `{{ project_name }}`.
- [:octicons-arrow-right-24: See Examples](examples/index.md)
+ [:octicons-arrow-right-24: See Examples](examples/index.md)
-- :material-file-document-outline: **Reference**
+- :material-file-document-outline: **Reference**
- ---
+ ______________________________________________________________________
- Full API reference, CLI documentation, and configuration schema.
+ Full API reference, CLI documentation, and configuration schema.
- [:octicons-arrow-right-24: View Reference](reference/index.md)
+ [:octicons-arrow-right-24: View Reference](reference/index.md)
-- :material-account-group-outline: **Community**
+- :material-account-group-outline: **Community**
- ---
+ ______________________________________________________________________
- Contributing guide, developer setup, Code of Conduct, and support resources.
+ Contributing guide, developer setup, Code of Conduct, and support resources.
- [:octicons-arrow-right-24: Get Involved](community/index.md)
+ [:octicons-arrow-right-24: Get Involved](community/index.md)
-- :material-shield-lock-outline: **Security**
+- :material-shield-lock-outline: **Security**
- ---
+ ______________________________________________________________________
- Our security policy, responsible disclosure process, and supported versions.
+ Our security policy, responsible disclosure process, and supported versions.
- [:octicons-arrow-right-24: Security Policy](community/security.md)
+ [:octicons-arrow-right-24: Security Policy](community/security.md)
-
## Quick Install
```bash
-
-# e.g., npm install {{project_name}} OR pip install {{project_name}}
+pip install project_name
```
For advanced installation options (from source, Docker, etc.) see the [Installation Guide](getting-started/installation.md).
-
## Links
-- :material-github: [GitHub Repository](https://github.com/{{ org_name }}/{{ project_name }})
-- :material-map-marker-path: [Roadmap]({{ roadmap_url }})
-- :material-post-outline: [Blog]({{ blog_url }})
-- :material-slack: [Slack Community]({{ slack_url }})
+
+
+- :material-github: \[GitHub Repository\](https://github.com/{{ org_name }}/{{ project_name }})
+- :material-map-marker-path: \[Roadmap\]({{ roadmap_url }})
+- :material-post-outline: \[Blog\]({{ blog_url }})
+- :material-slack: \[Slack Community\]({{ slack_url }})
+
+
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 4720b0c..24ce113 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -2,41 +2,50 @@
The Reference section contains the complete technical documentation for `{{ project_name }}` — API classes, CLI commands, and configuration options. This is the section to bookmark when you need to look something up.
-
## In This Section
-- :material-code-json: **API Reference**
+- :material-code-json: **API Reference**
- ---
+ ______________________________________________________________________
- Auto-generated documentation for all public classes, methods, and modules.
+ Auto-generated documentation for all public classes, methods, and modules.
-
- *Coming soon — see [Contributing](../community/contributing.md) to help.*
+
-- :material-console: **CLI Reference**
+ *Coming soon — see [Contributing](../community/contributing.md) to help.*
- ---
+- :material-console: **CLI Reference**
- Full documentation for all `{{ project_name }}` command-line interface commands,
- options, and flags.
+ ______________________________________________________________________
-
- *Coming soon.*
+ Full documentation for all `{{ project_name }}` command-line interface commands,
+ options, and flags.
-- :material-tune-variant: **Configuration Schema**
+
- ---
+ *Coming soon.*
- All supported configuration file options, types, defaults, and examples.
+- :material-tune-variant: **Configuration Schema**
-
- *Coming soon.*
+ ______________________________________________________________________
-
+ All supported configuration file options, types, defaults, and examples.
+
+
+
+ *Coming soon.*
+
+- :material-test-tube: **Test Coverage**
+
+ ______________________________________________________________________
+
+ Coverage reports are generated during CI/CD or locally.
+ Run `hatch run test:cov-all` to generate HTML reports in `docs/coverage/`.
+
+
## Generating API Reference Docs
@@ -47,25 +56,18 @@ This template is pre-configured to work with [`mkdocstrings`](https://mkdocstrin
> [!NOTE]
> `mkdocstrings` supports multiple languages via handlers (e.g., Python, C++, Crystal). See the [mkdocstrings documentation](https://mkdocstrings.github.io/) to configure it for your language.
-1. Install the plugin and your language handler (e.g., for Python):
-
- ```bash
- pip install mkdocstrings[python]
- ```
-
-2. Configure `mkdocs.yml` according to your language handler and create your reference pages.
-
+1. The plugin and its Python handler are already managed by Hatch in the `docs` environment (`mkdocstrings[python]`).
+1. Configure `mkdocs.yml` according to your language handler and create your reference pages.
## Generating CLI Reference Docs
For CLI documentation, consider using one of the following approaches depending on your CLI framework:
-| Framework | Plugin | Notes |
-| :--- | :--- | :--- |
-| **Typer** | [`typer-cli`](https://typer.tiangolo.com/typer-cli/) | Generates markdown from Typer apps |
-| **Click** | [`mkdocs-click`](https://github.com/brunoliveira8/mkdocs-click) | Auto-generates docs from Click decorators |
-| **Argparse** | Manual | Document commands in a dedicated `cli.md` page |
-
+| Framework | Plugin | Notes |
+| :----------- | :-------------------------------------------------------------- | :--------------------------------------------- |
+| **Typer** | [`typer-cli`](https://typer.tiangolo.com/typer-cli/) | Generates markdown from Typer apps |
+| **Click** | [`mkdocs-click`](https://github.com/brunoliveira8/mkdocs-click) | Auto-generates docs from Click decorators |
+| **Argparse** | Manual | Document commands in a dedicated `cli.md` page |
!!! tip "Template Reminder"
- Replace this page with actual generated reference documentation as your project matures. The placeholders above are intentional starting points.
+Replace this page with actual generated reference documentation as your project matures. The placeholders above are intentional starting points.
diff --git a/docs/requirements.txt b/docs/requirements.txt
deleted file mode 100644
index 2b17cec..0000000
--- a/docs/requirements.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-mkdocs>=1.6.0
-mkdocs-material>=9.5.0
-mkdocs-macros-plugin>=1.0.0
-pymdown-extensions>=10.7
diff --git a/examples/README.md b/examples/README.md
index d3b387f..4dc073a 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,51 +1,46 @@
-# {{project_name}} Examples
-
-This directory contains practical, runnable demonstrations of how to use `{{project_name}}` in various scenarios. These examples are designed to help you quickly understand core concepts, advanced configurations, and best practices.
+# project_name Examples
+This directory contains practical, runnable demonstrations of how to use `project_name` in various scenarios. These examples are designed to help you quickly understand core concepts, advanced configurations, and best practices.
## Prerequisites
Before running the examples, ensure you have set up your environment correctly:
1. **Install Dependencies:** Make sure you have installed the core package for your environment and any example-specific requirements.
-2. **Environment Variables:** Copy `.env.example` to `.env` if the examples require configuration (e.g., API keys or external services).
+1. **Environment Variables:** Copy `.env.example` to `.env` if the examples require configuration (e.g., API keys or external services).
> [!NOTE]
-> Some examples may require additional dependencies not included in the core `{{project_name}}` package. Please check the `README.md` within each specific example directory for details.
-
+> Some examples may require additional dependencies not included in the core `project_name` package. Please check the `README.md` within each specific example directory for details.
## Example Index
Below is a curated list of available examples, categorized by complexity:
-| Example | Complexity | Description |
-| :--- | :--- | :--- |
+| Example | Complexity | Description |
+| :----------------------------------- | :---------------------------- | :------------------------------------------------------------------- |
| **`[example_name/](example_name/)`** | ⭐ Beginner / ⭐⭐⭐ Advanced | Briefly describe the example and what core concepts it demonstrates. |
-
## Running the Examples
Most examples can be executed directly from the command line. Navigate to the root of the repository and run the desired script:
```bash
# Example: Running a generic example script
-
-# e.g., node examples/example_name/main.js OR python examples/example_name/main.py
+python examples/example_name/main.py
```
> [!TIP]
> **Always run examples from the repository root.** This ensures that all relative paths, environment variables, and module imports resolve correctly.
-
## Contributing New Examples
We welcome community contributions! If you have a use case that isn't covered, please consider submitting a new example:
1. Create a new directory under `examples/` with a descriptive name.
-2. Include a focused, easily digestible script or application.
-3. Add a local `README.md` within your example directory explaining what it does and how to run it.
-4. Update the **Example Index** table above.
+1. Include a focused, easily digestible script or application.
+1. Add a local `README.md` within your example directory explaining what it does and how to run it.
+1. Update the **Example Index** table above.
For more details on contributing, please review our [Contributing Guide](../CONTRIBUTING.md).
diff --git a/llms-full.txt b/llms-full.txt
index 879291d..d478539 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -1,4 +1,4 @@
-# {{project_name}} Full Documentation
+# project_name Full Documentation
This file contains the concatenated core documentation for the project to provide comprehensive context to LLMs.
@@ -8,7 +8,7 @@ This file contains the concatenated core documentation for the project to provid
-
+
@@ -18,33 +18,33 @@ This file contains the concatenated core documentation for the project to provid
@@ -70,11 +70,11 @@ This file contains the concatenated core documentation for the project to provid
-Welcome to the {{project_name}} template repository! This template provides a robust foundation for building high-quality, scalable software projects. It includes standard directories, issue templates, CI/CD workflows, and comprehensive placeholder documentation.
+Welcome to the project_name template repository! This template provides a robust foundation for building high-quality, scalable software projects. It includes standard directories, issue templates, CI/CD workflows, and comprehensive placeholder documentation.
-To use this template, simply find and replace all instances of `{{project_name}}` and `{{organization}}` with your actual project details, update the placeholder SVG images in `docs/assets/branding/`, and you are ready to start coding.
+To use this template, simply find and replace all instances of `project_name` and `{{organization}}` with your actual project details, update the placeholder SVG images in `docs/assets/branding/`, and you are ready to start coding.
-### Why Use {{project_name}}?
+### Why Use project_name?
- **Consistency:** Enforces a standardized layout and structure across your organization's repositories.
- **Speed:** Bootstraps your project with pre-configured Actions, badges, and templates so you don't start from scratch.
@@ -82,9 +82,9 @@ To use this template, simply find and replace all instances of `{{project_name}}
### Comparisons
-When evaluating {{project_name}} against other templates, consider the following differences:
+When evaluating project_name against other templates, consider the following differences:
-| Feature | {{project_name}} Template | Standard GitHub Init | Cookiecutter / Copier |
+| Feature | project_name Template | Standard GitHub Init | Cookiecutter / Copier |
| :--- | :--- | :--- | :--- |
| **Setup Speed** | Very Fast | Fast | Slower (requires CLI tool) |
| **Visual Assets** | Pre-configured Light/Dark assets | None | Varies |
@@ -94,7 +94,7 @@ When evaluating {{project_name}} against other templates, consider the following
## What's New
-**Welcome to the {{project_name}} Launch!**
+**Welcome to the project_name Launch!**
This project has just been instantiated from the template repository. Keep an eye on this section for future release highlights, new features, and community announcements!
@@ -103,10 +103,10 @@ This project has just been instantiated from the template repository. Keep an ey
## Quick Start
```bash
-pip install {{project_name}}
+pip install project_name
```
-For full installation options (from source, Docker, platform-specific notes) and step-by-step onboarding, see the **[Getting Started guide](https://{{organization}}.github.io/{{project_name}}/getting-started/)**.
+For full installation options (from source, Docker, platform-specific notes) and step-by-step onboarding, see the **[Getting Started guide](https://{{organization}}.github.io/project_name/getting-started/)**.
## Core Concepts
@@ -127,7 +127,7 @@ The template is organized into several key areas:
### Contributing
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details. For development setup, check out [DEVELOPING.md](DEVELOPING.md).
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details. For development setup, check out [DEVELOPING.md](DEVELOPING.md).
Please ensure you follow our [Code of Conduct](CODE_OF_CONDUCT.md) in all interactions.
### Support and Security
@@ -151,13 +151,13 @@ This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE
If you use this template or the resulting software in your research, please cite it using the following BibTeX entry:
```bibtex
-@software{{{project_name}},
+@software{project_name,
author = {{{organization}}},
- title = {{{project_name}}},
+ title = {project_name},
version = {{{version}}},
month = {{{month}}},
year = {2026},
- url = {https://github.com/{{organization}}/{{project_name}}}
+ url = {https://github.com/{{organization}}/project_name}
}
```
@@ -170,9 +170,9 @@ If you use this template or the resulting software in your research, please cite
## Project Context
-**`{{project_name}}`** is a production-ready Apache 2.0 template repository for bootstrapping modern software projects.
-**Primary language:** ``
-**Package manager:** ``
+**`project_name`** is a production-ready Apache 2.0 template repository for bootstrapping modern software projects.
+**Primary language:** ``
+**Package manager:** ``
## Critical Constraints
@@ -217,7 +217,7 @@ If you use this template or the resulting software in your research, please cite
- **`docs/`** and **`mkdocs.yml`** control the site. Do not create docs outside the `nav:` tree.
- `docs/index.md` dynamically includes `README.md` via MkDocs snippets.
-- Use `{{placeholder}}` variables for templated fields (e.g., `{{project_name}}`, `{{organization}}`).
+- Use `{{placeholder}}` variables for templated fields (e.g., `project_name`, `{{organization}}`).
## Agent Notes
@@ -225,7 +225,7 @@ _Add notes here when updating instructions for AI agents._
## File: DEVELOPING.md
-# Developing `{{project_name}}`
+# Developing `project_name`
This guide provides instructions for setting up your development environment, navigating the project structure, and adhering to our coding standards.
@@ -235,7 +235,7 @@ Ensure your system meets the following requirements before getting started:
- **[Docker](https://docs.docker.com/get-docker/)** (Recommended for isolated environments)
- **[Git](https://git-scm.com/)** (Version control)
--
+- Python 3.10+
> [!NOTE]
> We strongly recommend using our Docker setup to ensure your local environment exactly matches our CI/CD pipelines.
@@ -247,8 +247,8 @@ Ensure your system meets the following requirements before getting started:
>
> Once implemented, you can spin up the development environment with:
> ```bash
-> git clone https://github.com/{{organization}}/{{project_name}}.git
-> cd {{project_name}}
+> git clone https://github.com/{{organization}}/project_name.git
+> cd project_name
>
> # Build and start the development environment in the background
> docker-compose up -d --build
@@ -285,37 +285,6 @@ pip install -e ".[dev]"
pre-commit install
```
-### Node.js / TypeScript
-
-```bash
-# 1. Install all dependencies (uses lockfile for reproducibility)
-npm ci
-
-# 2. Install pre-commit hooks (requires Python; see note above)
-pre-commit install
-# Alternatively, use Husky for a pure Node.js hook solution:
-# npx husky install
-```
-
-### Go
-
-```bash
-# 1. Download module dependencies
-go mod download
-
-# 2. Install pre-commit hooks (requires Python; see note above)
-pre-commit install
-```
-
-### Rust
-
-```bash
-# 1. All dependencies are managed by Cargo automatically
-cargo build
-
-# 2. Install pre-commit hooks (requires Python; see note above)
-pre-commit install
-```
## Running Tests
@@ -335,18 +304,6 @@ pytest tests/unit/
pytest tests/integration/
pytest tests/ # full suite with coverage
pytest tests/ --cov=src --cov-report=xml
-
-# Node.js (Jest)
-npx jest tests/unit/
-npx jest --ci --coverage
-
-# Go
-go test ./tests/unit/...
-go test ./...
-
-# Rust
-cargo test --lib # unit tests
-cargo test --test '*' # integration tests
```
## Code Quality and Formatting
@@ -401,9 +358,9 @@ For further assistance, please refer to our [SUPPORT.md](SUPPORT.md).
## File: CONTRIBUTING.md
-# Contributing to {{project_name}}
+# Contributing to project_name
-First off, thank you for considering contributing to `{{project_name}}`! It's people like you that make this project great.
+First off, thank you for considering contributing to `project_name`! It's people like you that make this project great.
## Code of Conduct
@@ -418,13 +375,13 @@ If you discover a security issue, please refer to our [Security Policy](SECURITY
## How Can I Contribute?
-There are many ways to contribute to `{{project_name}}`, and not all of them involve writing code:
+There are many ways to contribute to `project_name`, and not all of them involve writing code:
- **Reporting Bugs:** Help us improve by submitting detailed bug reports via our issue tracker.
- **Suggesting Features:** Propose new features or enhancements that could benefit the project.
- **Improving Documentation:** Fix typos, add examples, or write new guides.
- **Writing Code:** Fix bugs, implement features, or improve performance.
-- **Helping Others:** Answer questions in [Discussions](https://github.com/{{organization}}/{{project_name}}/discussions) or issue comments.
+- **Helping Others:** Answer questions in [Discussions](https://github.com/{{organization}}/project_name/discussions) or issue comments.
For general questions and help, please see [SUPPORT.md](SUPPORT.md).
@@ -447,7 +404,7 @@ Before you start coding, please refer to our [Development Guide](DEVELOPING.md)
### 3. Making Changes
-1. **Fork the Repository:** Fork the `{{project_name}}` repository to your GitHub account.
+1. **Fork the Repository:** Fork the `project_name` repository to your GitHub account.
2. **Create a Branch:** Create a new branch from `main` for your work (e.g., `git checkout -b feat/add-new-feature`).
3. **Write Code:** Implement your changes, adhering to the project's coding standards.
4. **Write Tests:** Add unit tests or integration tests for your changes to ensure stability.
@@ -469,17 +426,17 @@ Before you start coding, please refer to our [Development Guide](DEVELOPING.md)
## Licensing
-By contributing to `{{project_name}}`, you agree that your contributions will be licensed under its [Apache 2.0 License](LICENSE).
+By contributing to `project_name`, you agree that your contributions will be licensed under its [Apache 2.0 License](LICENSE).
## File: SECURITY.md
-# Security Policy for `{{project_name}}`
+# Security Policy for `project_name`
-We take the security of `{{project_name}}` seriously. This document outlines our security policies, supported versions, and how to responsibly disclose a vulnerability.
+We take the security of `project_name` seriously. This document outlines our security policies, supported versions, and how to responsibly disclose a vulnerability.
## Supported Versions
-Please check the table below for the versions of `{{project_name}}` that are currently being supported with security updates.
+Please check the table below for the versions of `project_name` that are currently being supported with security updates.
| Version | Supported |
| :--- | :--- |
@@ -495,7 +452,7 @@ Please check the table below for the versions of `{{project_name}}` that are cur
If you discover a security vulnerability, please bring it to our attention right away using one of the following methods:
-1. **GitHub Security Advisories (Preferred):** Use the "Report a vulnerability" button on the **[Security tab](https://github.com/{{organization}}/{{project_name}}/security/advisories)** of this repository.
+1. **GitHub Security Advisories (Preferred):** Use the "Report a vulnerability" button on the **[Security tab](https://github.com/{{organization}}/project_name/security/advisories)** of this repository.
2. **Email:** Send your report directly to **[INSERT EMAIL ADDRESS OR SECURITY CONTACT]**. *(Optional: Encrypt your email using our PGP key: [INSERT PGP KEY LINK/FINGERPRINT])*
### What to Include in Your Report
@@ -505,7 +462,7 @@ To help us resolve the issue quickly, please include the following information:
- **Detailed description** of the vulnerability and its potential impact.
- **Step-by-step instructions** to reproduce the issue.
- **Proof of Concept (PoC)** code or screenshots, if available.
-- **Environment details** (e.g., version of `{{project_name}}`, OS, relevant configurations).
+- **Environment details** (e.g., version of `project_name`, OS, relevant configurations).
## Triage and Resolution Process
@@ -519,22 +476,22 @@ We will handle your report with strict confidentiality. Our process is as follow
## Scope
**In Scope:**
-- Vulnerabilities within the core `{{project_name}}` codebase.
+- Vulnerabilities within the core `project_name` codebase.
- Security issues in our default configurations.
**Out of Scope:**
- Volumetric Denial of Service (DoS) attacks.
- Theoretical issues without a reproducible PoC.
-- Vulnerabilities in third-party dependencies that are not exploitable through `{{project_name}}`.
+- Vulnerabilities in third-party dependencies that are not exploitable through `project_name`.
- Missing security headers or best practices that do not lead to a direct exploit.
*(Note: We currently **[do/do not]** operate a bug bounty program. Disclosures are greatly appreciated but are not eligible for financial rewards at this time.)*
## File: SUPPORT.md
-# Support for `{{project_name}}`
+# Support for `project_name`
-We are excited to have you use `{{project_name}}`! If you need help, please follow these guidelines to ensure you get support quickly and efficiently.
+We are excited to have you use `project_name`! If you need help, please follow these guidelines to ensure you get support quickly and efficiently.
## Security Vulnerabilities
@@ -547,9 +504,9 @@ If you have found a security vulnerability, please refer to our [Security Policy
Before reaching out, we recommend checking the following resources. Many common questions and issues are already covered there.
-- **[Official Documentation](https://{{organization}}.github.io/{{project_name}}):** Comprehensive guides, tutorials, and API references.
-- **[GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues):** Search existing issues to see if someone else has already reported your problem or requested your feature. Feel free to add a "+1" reaction to existing issues to show your interest.
-- **[GitHub Discussions](https://github.com/{{organization}}/{{project_name}}/discussions):** Search our discussions for Q&A, general advice, and community knowledge.
+- **[Official Documentation](https://{{organization}}.github.io/project_name):** Comprehensive guides, tutorials, and API references.
+- **[GitHub Issues](https://github.com/{{organization}}/project_name/issues):** Search existing issues to see if someone else has already reported your problem or requested your feature. Feel free to add a "+1" reaction to existing issues to show your interest.
+- **[GitHub Discussions](https://github.com/{{organization}}/project_name/discussions):** Search our discussions for Q&A, general advice, and community knowledge.
## Opening a New Issue
@@ -557,9 +514,9 @@ If you cannot find an answer in the documentation or existing issues, please ope
| Issue Type | Venue | Description |
| :--- | :--- | :--- |
-| **Bug Report** | [GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues/new) | Use the "Bug Report" template. Provide reproducible steps, environment details, and relevant logs. |
-| **Feature Request** | [GitHub Issues](https://github.com/{{organization}}/{{project_name}}/issues/new) | Use the "Feature Request" template. Clearly describe your use case and the problem the feature would solve. |
-| **Q&A / General Help** | [GitHub Discussions](https://github.com/{{organization}}/{{project_name}}/discussions/new) | Start a discussion for questions about how to use `{{project_name}}`, architecture queries, or advice. |
+| **Bug Report** | [GitHub Issues](https://github.com/{{organization}}/project_name/issues/new) | Use the "Bug Report" template. Provide reproducible steps, environment details, and relevant logs. |
+| **Feature Request** | [GitHub Issues](https://github.com/{{organization}}/project_name/issues/new) | Use the "Feature Request" template. Clearly describe your use case and the problem the feature would solve. |
+| **Q&A / General Help** | [GitHub Discussions](https://github.com/{{organization}}/project_name/discussions/new) | Start a discussion for questions about how to use `project_name`, architecture queries, or advice. |
## Community Channels
@@ -572,4 +529,4 @@ Join our community to chat with other users, contributors, and the core maintain
## Commercial Support
-At this time, there is no official commercial support available for `{{project_name}}`. Support is provided on a best-effort basis by the open-source community and maintainers.
+At this time, there is no official commercial support available for `project_name`. Support is provided on a best-effort basis by the open-source community and maintainers.
diff --git a/llms.txt b/llms.txt
index 69340ed..c964fa0 100644
--- a/llms.txt
+++ b/llms.txt
@@ -1,20 +1,20 @@
-# {{project_name}}
+# project_name
> An opinionated, production-ready Apache 2.0 template repository for bootstrapping modern software projects.
-`{{project_name}}` is designed to eliminate boilerplate and enforce consistency across an organization's repositories.
+`project_name` is designed to eliminate boilerplate and enforce consistency across an organization's repositories.
For comprehensive context and full documentation, please see [llms-full.txt](llms-full.txt).
## Docs
-- [Home](https://{{organization}}.github.io/{{project_name}}/): Documentation site home page
-- [Getting Started](https://{{organization}}.github.io/{{project_name}}/getting-started/): Installation, quickstart, and workflow guides
-- [Guides](https://{{organization}}.github.io/{{project_name}}/guides/): How-to guides for common tasks
-- [API Reference](https://{{organization}}.github.io/{{project_name}}/reference/): Full API reference documentation
+- [Home](https://{{organization}}.github.io/project_name/): Documentation site home page
+- [Getting Started](https://{{organization}}.github.io/project_name/getting-started/): Installation, quickstart, and workflow guides
+- [Guides](https://{{organization}}.github.io/project_name/guides/): How-to guides for common tasks
+- [API Reference](https://{{organization}}.github.io/project_name/reference/): Full API reference documentation
## Repository Files
-- [README.md](https://github.com/{{organization}}/{{project_name}}/blob/main/README.md): Project overview and quick start
-- [AGENTS.md](https://github.com/{{organization}}/{{project_name}}/blob/main/AGENTS.md): AI agent coding instructions
-- [DEVELOPING.md](https://github.com/{{organization}}/{{project_name}}/blob/main/DEVELOPING.md): Developer setup guide
+- [README.md](https://github.com/{{organization}}/project_name/blob/main/README.md): Project overview and quick start
+- [AGENTS.md](https://github.com/{{organization}}/project_name/blob/main/AGENTS.md): AI agent coding instructions
+- [DEVELOPING.md](https://github.com/{{organization}}/project_name/blob/main/DEVELOPING.md): Developer setup guide
## Optional
-- [Full Documentation](https://{{organization}}.github.io/{{project_name}}/llms-full.txt): The complete concatenated documentation for {{project_name}}
+- [Full Documentation](https://{{organization}}.github.io/project_name/llms-full.txt): The complete concatenated documentation for project_name
diff --git a/mkdocs.yml b/mkdocs.yml
index e2b5fe3..e02bb22 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,28 +1,26 @@
-site_name: "{{ project_name }}"
-site_description: "{{ project_description }}"
-site_author: "{{ org_name }}"
-site_url: "https://{{ org_name }}.github.io/{{ project_name }}/"
-
-repo_url: "https://github.com/{{ org_name }}/{{ project_name }}"
-repo_name: "{{ org_name }}/{{ project_name }}"
+---
+site_name: "{{project_name}}"
+site_description: "{{project_description}}"
+site_author: "{{org_name}}"
+site_url: "https://{{org_name}}.github.io/{{project_name}}/"
+repo_url: "https://github.com/{{org_name}}/{{project_name}}"
+repo_name: "{{org_name}}/{{project_name}}"
edit_uri: edit/main/docs/
-
# ---------------------------------------------------------------------------
# Template Variables — Update these when using this template.
# All {{ variable }} references across the docs site are driven from here.
# ---------------------------------------------------------------------------
extra:
- project_name: "{{project_name}}"
+ project_name: "project_name"
project_description: "{{project_description}}"
org_name: "{{organization}}"
org_email: "conduct@{{organization}}.com"
- docs_url: "https://{{organization}}.github.io/{{project_name}}"
+ docs_url: "https://{{org_name}}.github.io/{{project_name}}"
min_python: "3.9"
current_major_version: "0"
slack_url: "https://slack.{{organization}}.org"
blog_url: "https://blog.{{organization}}.org"
- roadmap_url: "https://github.com/{{organization}}/{{project_name}}/milestones"
-
+ roadmap_url: "https://github.com/{{organization}}/project_name/milestones"
theme:
name: material
features:
@@ -55,7 +53,6 @@ theme:
toggle:
icon: material/brightness-4
name: Switch to light mode
-
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
@@ -63,7 +60,8 @@ markdown_extensions:
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets:
- base_path: ["."]
+ base_path:
+ - "."
- pymdownx.superfences:
custom_fences:
- name: mermaid
@@ -78,36 +76,37 @@ markdown_extensions:
- tables
- toc:
permalink: true
-
plugins:
- search
- macros
-
+ - mkdocstrings:
+ handlers:
+ python:
+ paths:
+ - src
nav:
- Home: index.md
- Getting Started:
- - getting-started/index.md
- - Installation: getting-started/installation.md
- - Quick Start: getting-started/quickstart.md
- - Workflows: getting-started/workflows.md
+ - getting-started/index.md
+ - Installation: getting-started/installation.md
+ - Quick Start: getting-started/quickstart.md
+ - Workflows: getting-started/workflows.md
- Guides: guides/index.md
- Examples: examples/index.md
- - Reference: reference/index.md
+ - Reference:
+ - reference/index.md
- Community:
- - community/index.md
- - Contributing: community/contributing.md
- - Developer Setup: community/developing.md
- - AI Agent Guide: community/agents.md
- - Code of Conduct: community/code-of-conduct.md
- - Security Policy: community/security.md
- - Support: community/support.md
-
+ - community/index.md
+ - Contributing: community/contributing.md
+ - Developer Setup: community/developing.md
+ - AI Agent Guide: community/agents.md
+ - Code of Conduct: community/code-of-conduct.md
+ - Security Policy: community/security.md
+ - Support: community/support.md
extra_css:
- stylesheets/extra.css
-
extra_javascript:
- scripts/extra.js
-
# ---------------------------------------------------------------------------
# LLM & AI Tooling
# ---------------------------------------------------------------------------
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..0ecfcae
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,291 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "project_name"
+dynamic = ["version"]
+description = "{{project_description}}"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "{{organization}}" }]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+ # testing
+ "pytest>=8.0.0",
+ "pytest-asyncio",
+ "pytest-cov",
+ "pytest-mock",
+ "respx",
+
+ # code quality
+ "mypy",
+ "ruff",
+
+ # docs quality
+ "mdformat",
+ "mdformat-frontmatter",
+ "mdformat-gfm",
+
+ # general and configurations
+ "yamlfix",
+]
+docs = [
+ # documentation
+ "mike",
+ "mkdocs>=1.6.0",
+ "mkdocs-macros-plugin",
+ "mkdocs-material>=9.5.0",
+ "pymdown-extensions",
+]
+
+[project.scripts]
+project_name = "project_name.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/{{org_name}}/{{project_name}}"
+Repository = "https://github.com/{{org_name}}/{{project_name}}.git"
+Issues = "https://github.com/{{org_name}}/{{project_name}}/issues"
+
+[tool.hatch.version]
+path = "src/project_name/__init__.py"
+
+# ==============================================================================
+# Hatch Environment Configurations
+# ==============================================================================
+
+[tool.hatch.envs.default]
+installer = "uv"
+dependencies = [
+ "pytest",
+ "pytest-cov",
+ "pytest-mock",
+ "pytest-asyncio",
+ "respx",
+]
+
+# ------------------------------------------------------------------------------
+# Quality & Style: Ruff, mdformat, yamlfix
+# ------------------------------------------------------------------------------
+[tool.hatch.envs.lint]
+detached = true
+installer = "uv"
+dependencies = [
+ "pre-commit",
+ "ruff",
+ "mdformat",
+ "mdformat-gfm",
+ "mdformat-frontmatter",
+ "yamlfix>=1.16.0",
+]
+
+[tool.hatch.envs.lint.scripts]
+# Quality checks (Read-only)
+check = [
+ "ruff check {args:.}",
+ "ruff format --check {args:.}",
+ "mdformat --check {args:.}",
+ "yamlfix --check {args:.}",
+]
+pre-commit = "SKIP=type-check pre-commit run --all-files --show-diff-on-failure"
+# Style runs (Applies fixes)
+format = [
+ "ruff check --fix {args:.}",
+ "ruff format {args:.}",
+ "mdformat {args:.}",
+ "yamlfix {args:.}",
+]
+
+# ------------------------------------------------------------------------------
+# Type Checking: Mypy
+# ------------------------------------------------------------------------------
+[tool.hatch.envs.types]
+# Needs project dependencies to resolve imports
+template = "default"
+dependencies = [
+ "mypy>=1.0.0",
+]
+
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src tests}"
+
+# ------------------------------------------------------------------------------
+# Testing: Pytest with segmented coverage
+# ------------------------------------------------------------------------------
+[tool.hatch.envs.test]
+# Use the default env which contains pytest and pytest-cov
+template = "default"
+
+[tool.hatch.envs.test.scripts]
+# Standard runs (no coverage)
+all = "pytest tests {args}"
+unit = "pytest tests/unit {args}"
+integration = "pytest tests/integration {args}"
+e2e = "pytest tests/e2e {args}"
+
+# Coverage specific runs
+# These use --cov=src to ensure only your source code is measured
+cov-unit = "pytest --cov=src --cov-report=term-missing --cov-report=html:docs/coverage/unit/htmlcov tests/unit {args}"
+cov-integration = "pytest --cov=src --cov-report=term-missing --cov-report=html:docs/coverage/integration/htmlcov tests/integration {args}"
+cov-e2e = "pytest --cov=src --cov-report=term-missing --cov-report=html:docs/coverage/e2e/htmlcov tests/e2e {args}"
+# Full suite coverage
+cov-all = "pytest --cov=src --cov-report=term-missing --cov-report=html:docs/coverage/all/htmlcov tests {args}"
+
+# ------------------------------------------------------------------------------
+# Documentation: MkDocs
+# ------------------------------------------------------------------------------
+[tool.hatch.envs.docs]
+detached = true
+installer = "uv"
+dependencies = [
+ "mkdocs>=1.6.0",
+ "mkdocs-material>=9.5.0",
+ "mkdocstrings[python]",
+ "mike",
+ "pymdown-extensions",
+ "mkdocs-macros-plugin",
+]
+
+[tool.hatch.envs.docs.scripts]
+build = "mkdocs build --clean --strict"
+serve = "mkdocs serve --dev-addr 0.0.0.0:8000"
+
+# ------------------------------------------------------------------------------
+# Build Configuration (hatch build)
+# ------------------------------------------------------------------------------
+[tool.hatch.build.targets.sdist]
+exclude = [
+ "/.github",
+ "/docs",
+ "/tests",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/project_name"]
+
+
+# --- Tool Configurations ---
+[tool.mypy]
+files = ["src/project_name", "tests"]
+python_version = "3.10"
+warn_redundant_casts = true
+warn_unused_ignores = false
+show_error_codes = true
+namespace_packages = true
+exclude = ["venv", "build", "dist", ".venv"]
+follow_imports = "silent"
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+exclude = ["build", "dist", "env", ".venv"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint]
+ignore = [
+ "COM812", # ignore trailing comma errors due to older Python versions
+ "ISC001", # implicit string concatenation (often disabled when using ruff format)
+ "PD011", # ignore .values usage since ruff assumes it's a Pandas DataFrame
+ "PLR0913", # ignore too many arguments in function definitions
+ "PLW1514", # allow Path.open without encoding
+ "RET505", # allow `else` blocks
+ "RET506", # allow `else` blocks
+ "S311", # allow standard pseudo-random generators
+ "TC001", # ignore imports used only for type checking
+ "TC002", # ignore imports used only for type checking
+ "TC003", # ignore imports used only for type checking
+]
+select = [
+ # Rules reference: https://docs.astral.sh/ruff/rules/
+
+ # Code Style / Formatting
+ "E", # pycodestyle: checks adherence to PEP 8 conventions including spacing, indentation, and line length
+ "W", # pycodestyle: checks adherence to PEP 8 conventions including spacing, indentation, and line length
+ "A", # flake8-builtins: prevents shadowing of Python built-in names
+ "C", # Convention: ensures code adheres to specific style and formatting conventions
+ "COM", # flake8-commas: enforces the correct use of trailing commas
+ "ERA", # eradicate: detects commented-out code that should be removed
+ "I", # isort: ensures imports are sorted in a consistent manner
+ "ICN", # flake8-import-conventions: enforces import conventions for better readability
+ "N", # pep8-naming: enforces PEP 8 naming conventions for classes, functions, and variables
+ "NPY", # NumPy: enforces best practices for using the NumPy library
+ "PD", # pandas-vet: enforces best practices for using the pandas library
+ "PT", # flake8-pytest-style: enforces best practices and style conventions for pytest tests
+ "PTH", # flake8-use-pathlib: encourages the use of pathlib over os.path for file system operations
+ "Q", # flake8-quotes: enforces consistent use of single or double quotes
+ "TCH", # flake8-type-checking: enforces type checking practices and standards
+ "TID", # flake8-tidy-imports: enforces tidy and well-organized imports
+ "RUF022", # flake8-ruff: enforce sorting of __all__ in modules
+
+ # Code Structure / Complexity
+ "C4", # flake8-comprehensions: improves readability and performance of list, set, and dict comprehensions
+ "C90", # mccabe: checks for overly complex code using cyclomatic complexity
+ "ISC", # flake8-implicit-str-concat: prevents implicit string concatenation
+ "PIE", # flake8-pie: identifies and corrects common code inefficiencies and mistakes
+ "R", # Refactor: suggests improvements to code structure and readability
+ "SIM", # flake8-simplify: simplifies complex expressions and improves code readability
+
+ # Code Security / Bug Prevention
+ "ARG", # flake8-unused-arguments: detects unused function and method arguments
+ "ASYNC", # flake8-async: identifies incorrect or inefficient usage patterns in asynchronous code
+ "B", # flake8-bugbear: detects common programming mistakes and potential bugs
+ "BLE", # flake8-blind-except: prevents blind exceptions that catch all exceptions without handling
+ "E", # Error: detects and reports errors in the code
+ "F", # Pyflakes: detects unused imports, shadowed imports, undefined variables, and various formatting errors in string operations
+ "INP", # flake8-no-pep420: prevents implicit namespace packages by requiring __init__.py
+ "PGH", # pygrep-hooks: detects deprecated and dangerous code patterns
+ "PL", # Pylint: comprehensive source code analyzer for enforcing coding standards and detecting errors
+ "RSE", # flake8-raise: ensures exceptions are raised correctly
+ "S", # flake8-bandit: detects security issues and vulnerabilities in the code
+ "SLF", # flake8-self: prevents incorrect usage of the self argument in class methods
+ "T10", # flake8-debugger: detects the presence of debugging tools such as pdb
+ "T20", # flake8-print: detects print statements left in the code
+ "UP", # pyupgrade: automatically upgrades syntax for newer versions of Python
+ "W", # Warning: provides warnings about potential issues in the code
+ "YTT", # flake8-2020: identifies code that will break with future Python releases
+
+ # Code Documentation
+ "FIX", # flake8-fixme: detects FIXMEs and other temporary comments that should be resolved
+]
+
+[tool.ruff.lint.extend-per-file-ignores]
+"tests/**/*.py" = [
+ "S101", # asserts allowed in tests
+ "ARG", # Unused function args allowed in tests
+ "PLR2004", # Magic value used in comparison
+ "TCH002", # No import only type checking in tests
+ "SLF001", # enable private member access in tests
+ "S105", # allow hardcoded passwords in tests
+ "S106", # allow hardcoded passwords in tests
+ "S311", # allow standard pseudo-random generators in tests
+ "PT011", # allow generic exceptions in tests
+ "N806", # allow uppercase variable names in tests
+ "PGH003", # allow general ignores in tests
+ "PLR0915", # allow complex statements in tests
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["project_name", "tests"]
+
+[tool.pytest.ini_options]
+addopts = "-s -vvv --cache-clear"
+asyncio_mode = "auto"
+markers = [
+ "smoke: quick tests to check basic functionality",
+ "sanity: detailed tests to ensure major functions work correctly",
+ "regression: tests to ensure that new changes do not break existing functionality",
+ "e2e: end-to-end integration tests"
+]
+testpaths = ["tests"]
+
+[tool.yamlfix]
+line_length = 88
+sequence_style = "block_style"
+preserve_quotes = true
diff --git a/scripts/README.md b/scripts/README.md
index 2bed465..4e853c7 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -1,11 +1,10 @@
-# `{{project_name}}` - Utility Scripts
+# `project_name` - Utility Scripts
-This directory contains utility scripts designed to assist with local development, maintenance, and automation tasks for `{{project_name}}`.
+This directory contains utility scripts designed to assist with local development, maintenance, and automation tasks for `project_name`.
> [!NOTE]
> These scripts are intended for developer and CI/CD use only and are **not** distributed as part of the final application package.
-
## Usage Guidelines
To ensure a consistent development experience across the organization, please adhere to the following guidelines when running or adding scripts.
@@ -35,14 +34,12 @@ If you are adding or modifying a script in this directory, please ensure it adhe
- **Provide Help:** Scripts should ideally accept a `-h` or `--help` flag that outputs usage instructions.
- **Log Clearly:** Prefix output with `[INFO]`, `[WARN]`, or `[ERROR]` to make CI/CD logs easier to read.
-
## Available Scripts
-| Script | Description |
-| :--- | :--- |
-| `setup_dev_env.sh` | *(Example)* Bootstraps the local development environment. |
-| `release.sh` | *(Example)* Automates the version bumping and release tagging process. |
-
+| Script | Description |
+| :----------------- | :--------------------------------------------------------------------- |
+| `setup_dev_env.sh` | *(Example)* Bootstraps the local development environment. |
+| `release.sh` | *(Example)* Automates the version bumping and release tagging process. |
## Contributing
diff --git a/scripts/bootstrap.sh b/scripts/bootstrap.sh
index 77d2d98..ec732f7 100755
--- a/scripts/bootstrap.sh
+++ b/scripts/bootstrap.sh
@@ -2,7 +2,7 @@
# =============================================================================
# bootstrap.sh — Template Initialization
#
-# Automatically replaces all template placeholders (e.g., {{project_name}})
+# Automatically replaces all template placeholders (e.g., project_name)
# with your actual project values.
#
# Usage:
@@ -17,7 +17,7 @@ if [[ $# -eq 0 ]] || [[ "$1" == "-h" ]] || [[ "$1" == "--help" ]]; then
echo "Bootstraps the repository by replacing template variables."
echo ""
echo "Options:"
- echo " --project-name NAME Replacement for {{project_name}}"
+ echo " --project-name NAME Replacement for project_name"
echo " --project-desc DESC Replacement for {{project_description}}"
echo " --organization ORG Replacement for {{organization}}"
echo " --org-name ORG Replacement for {{org_name}}"
@@ -76,6 +76,18 @@ while [[ $# -gt 0 ]]; do
esac
done
+if [[ -z "$PROJECT_NAME" ]] || [[ -z "$PROJECT_DESC" ]] || [[ -z "$ORGANIZATION" ]] || [[ -z "$ORG_NAME" ]]; then
+ echo "[ERROR] Missing required arguments."
+ echo "All of the following options must be provided:"
+ echo " --project-name"
+ echo " --project-desc"
+ echo " --organization"
+ echo " --org-name"
+ echo ""
+ echo "Use $0 --help for usage guidance."
+ exit 1
+fi
+
echo "[INFO] Starting repository bootstrap..."
export PROJECT_NAME
@@ -84,21 +96,23 @@ export ORGANIZATION
export ORG_NAME
python3 -c "
-import os, sys
+import os, sys, shutil
+
+project_name = os.environ.get('PROJECT_NAME', '')
+python_pkg = project_name.replace('-', '_')
replacements = {
- '{{project_name}}': os.environ.get('PROJECT_NAME', ''),
+ '{{project_name}}': project_name,
+ '%7B%7Bproject_name%7D%7D': project_name,
+ 'project_name': python_pkg,
'{{project_description}}': os.environ.get('PROJECT_DESC', ''),
+ '%7B%7Bproject_description%7D%7D': os.environ.get('PROJECT_DESC', ''),
'{{organization}}': os.environ.get('ORGANIZATION', ''),
- '{{org_name}}': os.environ.get('ORG_NAME', '')
+ '%7B%7Borganization%7D%7D': os.environ.get('ORGANIZATION', ''),
+ '{{org_name}}': os.environ.get('ORG_NAME', ''),
+ '%7B%7Borg_name%7D%7D': os.environ.get('ORG_NAME', '')
}
-# Filter out empty arguments
-replacements = {k: v for k, v in replacements.items() if v}
-
-if not replacements:
- print('[INFO] No replacements provided. Use -h for options.')
- sys.exit(0)
ignore_dirs = {'.git', '.venv', 'node_modules', 'site', '__pycache__', 'assets'}
ignore_exts = ('.pyc', '.png', '.svg', '.jpg', '.jpeg', '.gif', '.ico', '.woff', '.woff2', '.ttf', '.eot')
@@ -108,23 +122,30 @@ for root, dirs, files in os.walk('.'):
for file in files:
if file.endswith(ignore_exts) or file == 'bootstrap.sh':
continue
-
+
filepath = os.path.join(root, file)
-
+
try:
with open(filepath, 'r', encoding='utf-8') as f:
content = f.read()
except UnicodeDecodeError:
continue
-
+
new_content = content
for placeholder, replacement in replacements.items():
new_content = new_content.replace(placeholder, replacement)
-
+
if content != new_content:
with open(filepath, 'w', encoding='utf-8') as f:
f.write(new_content)
print(f'[INFO] Updated: {filepath}')
+
+src_dir = os.path.join('.', 'src', 'project_name')
+dst_dir = os.path.join('.', 'src', python_pkg)
+if os.path.exists(src_dir) and src_dir != dst_dir:
+ os.rename(src_dir, dst_dir)
+ print(f'[INFO] Renamed directory: {src_dir} -> {dst_dir}')
+
"
echo "[INFO] Bootstrap complete! You may now delete this script if desired."
diff --git a/src/{{project_name}}/.gitkeep b/src/project_name/.gitkeep
similarity index 100%
rename from src/{{project_name}}/.gitkeep
rename to src/project_name/.gitkeep
diff --git a/src/project_name/__init__.py b/src/project_name/__init__.py
new file mode 100644
index 0000000..3dd0b09
--- /dev/null
+++ b/src/project_name/__init__.py
@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
diff --git a/src/project_name/__main__.py b/src/project_name/__main__.py
new file mode 100644
index 0000000..2bdfc20
--- /dev/null
+++ b/src/project_name/__main__.py
@@ -0,0 +1,23 @@
+# ---------------------------------------------------------
+# {{project_name}} # noqa: ERA001
+# Licensed under the Apache License, Version 2.0
+# ---------------------------------------------------------
+"""Main entrypoint for the {{project_name}} package."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> int:
+ """Execute the main routine."""
+ logging.basicConfig(level=logging.INFO)
+ logger.info("Hello from {{project_name}}!")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/src/project_name/py.typed b/src/project_name/py.typed
new file mode 100644
index 0000000..e69de29
diff --git a/test.md b/test.md
new file mode 100644
index 0000000..1e3c2c5
--- /dev/null
+++ b/test.md
@@ -0,0 +1 @@
+[View on GitHub](https://github.com/%7B%7Borg_name%7D%7D/%7B%7Bproject_name%7D%7D){ .md-button }
diff --git a/test2.md b/test2.md
new file mode 100644
index 0000000..dfa753e
--- /dev/null
+++ b/test2.md
@@ -0,0 +1 @@
+[link](http://a.com/%7B%7Btest%7D%7D)
diff --git a/test_link.md b/test_link.md
new file mode 100644
index 0000000..2c96ea1
--- /dev/null
+++ b/test_link.md
@@ -0,0 +1 @@
+[View on GitHub](https://github.com/%7B%7B%20org_name%20%7D%7D/%7B%7B%20project_name%20%7D%7D)
diff --git a/test_snippet.md b/test_snippet.md
new file mode 100644
index 0000000..6cb61e8
--- /dev/null
+++ b/test_snippet.md
@@ -0,0 +1,5 @@
+
+
+--8\<-- "DEVELOPING.md"
+
+
diff --git a/tests/e2e/__init__.py b/tests/e2e/__init__.py
new file mode 100644
index 0000000..626cf5a
--- /dev/null
+++ b/tests/e2e/__init__.py
@@ -0,0 +1 @@
+# E2E tests package.
diff --git a/tests/e2e/test_e2e.py b/tests/e2e/test_e2e.py
new file mode 100644
index 0000000..87b9591
--- /dev/null
+++ b/tests/e2e/test_e2e.py
@@ -0,0 +1,24 @@
+"""Example end-to-end tests for the project."""
+
+import pytest
+
+
+@pytest.mark.smoke
+@pytest.mark.e2e
+def test_smoke_e2e_example() -> None:
+ """A basic smoke test for end-to-end functionality."""
+ assert True
+
+
+@pytest.mark.sanity
+@pytest.mark.e2e
+def test_sanity_e2e_example() -> None:
+ """A sanity test for end-to-end functionality."""
+ assert True
+
+
+@pytest.mark.regression
+@pytest.mark.e2e
+def test_regression_e2e_example() -> None:
+ """A regression test for end-to-end functionality."""
+ assert True
diff --git a/tests/integration/__init__.py b/tests/integration/__init__.py
new file mode 100644
index 0000000..a78ea06
--- /dev/null
+++ b/tests/integration/__init__.py
@@ -0,0 +1 @@
+# Integration tests package.
diff --git a/tests/integration/test_integration.py b/tests/integration/test_integration.py
new file mode 100644
index 0000000..09eea9b
--- /dev/null
+++ b/tests/integration/test_integration.py
@@ -0,0 +1,21 @@
+"""Example integration tests for the project."""
+
+import pytest
+
+
+@pytest.mark.smoke
+def test_smoke_integration_example() -> None:
+ """A basic smoke test for integration functionality."""
+ assert True
+
+
+@pytest.mark.sanity
+def test_sanity_integration_example() -> None:
+ """A sanity test for integration functionality."""
+ assert True
+
+
+@pytest.mark.regression
+def test_regression_integration_example() -> None:
+ """A regression test for integration functionality."""
+ assert True
diff --git a/tests/unit/__init__.py b/tests/unit/__init__.py
new file mode 100644
index 0000000..1a351fa
--- /dev/null
+++ b/tests/unit/__init__.py
@@ -0,0 +1 @@
+# Unit tests package.
diff --git a/tests/unit/test_unit.py b/tests/unit/test_unit.py
new file mode 100644
index 0000000..c2716bc
--- /dev/null
+++ b/tests/unit/test_unit.py
@@ -0,0 +1,21 @@
+"""Example unit tests for the project."""
+
+import pytest
+
+
+@pytest.mark.smoke
+def test_smoke_example() -> None:
+ """A basic smoke test to ensure the unit test suite runs."""
+ assert True
+
+
+@pytest.mark.sanity
+def test_sanity_example() -> None:
+ """A sanity test for detailed unit testing."""
+ assert True
+
+
+@pytest.mark.regression
+def test_regression_example() -> None:
+ """A regression test for unit testing."""
+ assert True
+ 
+
+ 
