serious-scaffold · huxuan · Aug 14, 2023 · Aug 14, 2023 · Aug 14, 2023 · Aug 14, 2023
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -20,13 +20,17 @@
     "cobertura",
     "codecov",
     "epub",
+    "furo",
     "huxuan",
     "interruptible",
     "isort",
     "mypy",
     "pathjoin",
     "pipenv",
+    "pipx",
     "pydantic",
+    "pytest",
+    "Quickstart",
     "setuptools",
     "typer"
   ],

diff --git a/README.md b/README.md
@@ -2,81 +2,99 @@
 
 A development-focused Python project template with various integrations, configurations and modules.
 
-[![GitHub](https://img.shields.io/github/license/serious-scaffold/serious-scaffold-python)](https://github.com/serious-scaffold/serious-scaffold-python/blob/main/LICENSE)
 [![CI Status](https://github.com/serious-scaffold/serious-scaffold-python/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/serious-scaffold/serious-scaffold-python/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/serious-scaffold/serious-scaffold-python/branch/main/graph/badge.svg?token=4JPKXI122N)](https://codecov.io/gh/serious-scaffold/serious-scaffold-python)
 [![Documentation Status](https://readthedocs.org/projects/serious-scaffold-python/badge/)](https://serious-scaffold-python.readthedocs.io/)
+[![GitHub](https://img.shields.io/github/license/serious-scaffold/serious-scaffold-python)](https://github.com/serious-scaffold/serious-scaffold-python/blob/main/LICENSE)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/serious-scaffold)](https://pypi.org/project/serious-scaffold/)
+[![PyPI](https://img.shields.io/pypi/v/serious-scaffold)](https://pypi.org/project/serious-scaffold/)
+
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
-[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/5697b1e4c4a9790ece607654e6c02a160620c7e1/docs/badge/v2.json)](https://pydantic.dev)
 [![Serious Scaffold Python](https://img.shields.io/badge/serious%20scaffold-python-blue)](https://github.com/serious-scaffold/serious-scaffold-python)
-[![PyPI](https://img.shields.io/pypi/v/serious-scaffold)](https://pypi.org/project/serious-scaffold/)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/serious-scaffold)](https://pypi.org/project/serious-scaffold/)
 
-<div align="center">
-  <a href="https://github.com/serious-scaffold/serious-scaffold-python">
-    <img src="docs/_static/images/logo.png" height=300 alt="Serious Scaffold Python">
-  </a>
-</div>
+[![Serious Scaffold Python](docs/_static/images/logo.svg)](https://github.com/serious-scaffold/serious-scaffold-python)
 
-Many efforts have been made to ease the project setup, but most of them are only language-specified basic components. In practice, we have to deal with much more details, especially for team projects. Many commonly used tools and configurations need to be handled properly. Moreover, different people tend to have different favors in various aspects. If you are tired of the inefficient setup process and endless discussion, [Serious Scaffold Python](https://github.com/serious-scaffold/serious-scaffold-python) is here to terminate those for Python Projects.
+Project setup often involves more than just creating a basic project structure. It includes tasks like setting up GitHub Actions or GitLab CI/CD, configuring linters, tests and documentation, and implementing settings and logging modules. If you are tired of this repetitive process, [Serious Scaffold Python](https://github.com/serious-scaffold/serious-scaffold-python) is here to help. Utilizing the power of [`copier`](https://copier.readthedocs.io/), you can generate a new Python project with just one command. Simply answer a few questions, and your project will be fully set up. Additionally, your project can be updated alongside the advancement of the template.
 
 If you find this helpful, please consider [sponsorship](https://github.com/sponsors/huxuan).
 
-## Features
-
-- Basic Python project structure as a package with tests and documentation.
-- Categorized requirements management with constraints for different environments.
-- [`typer`](https://github.com/tiangolo/typer) for CLI with tests and automatic documentation generation.
-- [`pydantic`](https://github.com/pydantic/pydantic) for [settings](https://pydantic-docs.helpmanual.io/usage/settings/) with tests and documentation as module samples.
-- [`setuptools-scm`](https://github.com/pypa/setuptools_scm/) to extract the version for the package.
-- [`black`](https://github.com/psf/black), [`isort`](https://pycqa.github.io/isort/), [`mypy`](http://www.mypy-lang.org/), [`ruff`](https://github.com/charliermarsh/ruff) and [`toml-sort`](https://github.com/pappasam/toml-sort) as linters.
-- [`pre-commit`](https://github.com/pre-commit/pre-commit) with [general hooks](https://github.com/pre-commit/pre-commit-hooks) and local linters.
-- `Makefile` as the entry point for common actions.
-- VSCode settings with recommended extensions.
-- GitHub workflows for lint, tests, package and documentation preview.
-
-## Quickstart
-
-1. [Install Copier](https://copier.readthedocs.io/en/stable/#installation).
-1. Install the necessary tools for development: `pipenv` and `pre-commit`.
-1. Generate the project with the `copier` command.
-
-   ```
+## 🛠 Features
+
+- **Template Rendering**
+  - Harness [`copier`](https://copier.readthedocs.io/) to initiate projects and enable template updates.
+- **Environment Management**
+  - Utilize [`pipenv`](https://pipenv.pypa.io/) for virtual environment management.
+  - Use containers and system-level `pip` for CI/CD.
+- **Dependency Management**
+  - Manage dependencies categorically with [constraints](https://pip.pypa.io/en/stable/user_guide/#constraints-files) for different environments.
+- **Code Quality Checks**
+  - Incorporate linters including [`black`](https://github.com/psf/black), [`isort`](https://pycqa.github.io/isort/), [`mypy`](http://www.mypy-lang.org/), [`ruff`](https://github.com/charliermarsh/ruff), and [`toml-sort`](https://github.com/pappasam/toml-sort).
+  - Integrate [`pre-commit`](https://github.com/pre-commit/pre-commit) for Git hooks automation.
+- **Tests**
+  - Execute tests with [`pytest`](https://pytest.org/), supplemented by [`coverage`](https://coverage.readthedocs.io) reports and thresholds.
+- **Documentation**
+  - Use [`sphinx`](https://www.sphinx-doc.org/) with the [`furo`](https://pradyunsg.me/furo) theme.
+  - Include [MyPy](https://mypy.readthedocs.io/en/stable/command_line.html?report-generation) and [Coverage](https://coverage.readthedocs.io/en/7.3.0/cmd.html#html-reporting-coverage-html) reports.
+- **Continuous Integration**
+  - Offer a unified `Makefile` for common actions.
+  - Provide configurations for [GitHub Actions](https://docs.github.com/actions) and [GitLab CI/CD](https://docs.gitlab.com/ee/ci/).
+  - Support [Read the Docs](https://readthedocs.org/) integration.
+- **Common Modules**
+  - Use [`typer`](https://typer.tiangolo.com/) for CLI tasks, including tests, documentation, and configuration.
+  - Adopt [`setuptools-scm`](https://github.com/pypa/setuptools_scm/) for versioning via git metadata.
+  - Implement [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) for robust settings management.
+- **Miscellaneous**
+  - Offer VSCode [settings](.vscode/settings.json) and recommended [extensions](.vscode/extensions.json).
+
+## 🔧 Prerequisites
+
+Certain system-level Python applications are needed and it is recommended to use [`pipx`](https://pypa.github.io/pipx/) to install and run them in isolated environments. Refer to pipx's installation instructions [here](https://pypa.github.io/pipx/installation/). Once `pipx` is set up, install the necessary tools using the following commands.
+
+```bash
+# Copier: Template rendering for projects.
+pipx install copier
+
+# Pipenv: Virtual environment and package manager for Python.
+pipx install pipenv
+
+# Pre-commit: Automates Git hooks for code quality checks.
+pipx install pre-commit
+```
+
+## 🚀 Quickstart
+
+1. Generate the project by answering several questions.
+
+   ```bash
    copier copy gh:serious-scaffold/serious-scaffold-python /path/to/project
    ```
 
-1. Initialize the project with the `git` and `make` commands.
+1. Initialize an empty git repository.
 
-   ```
+   ```bash
    cd /path/to/project
    git init
-   git add .
-   make dev
-   make pre-commit
-   git commit -a -m "Init from serious-scaffold-python."
    ```
 
-1. Happy hacking.
+1. Prepare development environment.
 
-## Roadmap
+   ```bash
+   make dev
+   ```
 
-- More detailed documentation for usage.
-- More detailed documentation for features.
-- Add logging module.
-- Refine README template.
-- [Github Automatically generated release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes) integration.
-- [GitHub Dependabot](https://github.com/dependabot) integration.
-- [GitHub issue and pull request templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests).
-- [Gitlab CI/CD](https://docs.gitlab.com/ee/ci/) integration.
-- [Gitlab issue and merge request templates](https://docs.gitlab.com/ee/user/project/description_templates.html).
+1. Commit the initialized project.
 
-## License
+   ```bash
+   git add .
+   git commit -m "Init from serious-scaffold-python."
+   ```
 
-MIT
+1. Initialization Done! Focus on the logical code within `src` folder now.
 
-## Contributing
+## 📜 License
 
-Any suggestions, discussions and bug fixing are all welcome.
+MIT, for more details, see the [LICENSE](LICENSE) file.
diff --git a/README.md.jinja b/README.md.jinja
@@ -2,81 +2,99 @@
 
 {{ project_description }}
 
-[![GitHub](https://img.shields.io/github/license/{{ repo_namespace }}/{{ repo_name }})](https://github.com/{{ repo_namespace }}/{{ repo_name }}/blob/main/LICENSE)
 [![CI Status](https://github.com/{{ repo_namespace }}/{{ repo_name }}/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/{{ repo_namespace }}/{{ repo_name }}/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/{{ repo_namespace }}/{{ repo_name }}/branch/main/graph/badge.svg?token=4JPKXI122N)](https://codecov.io/gh/{{ repo_namespace }}/{{ repo_name }})
 [![Documentation Status](https://readthedocs.org/projects/{{ repo_name }}/badge/)](https://{{ repo_name }}.readthedocs.io/)
+[![GitHub](https://img.shields.io/github/license/{{ repo_namespace }}/{{ repo_name }})](https://github.com/{{ repo_namespace }}/{{ repo_name }}/blob/main/LICENSE)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/{{ package_name }})](https://pypi.org/project/{{ package_name }}/)
+[![PyPI](https://img.shields.io/pypi/v/{{ package_name }})](https://pypi.org/project/{{ package_name }}/)
+
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
-[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/5697b1e4c4a9790ece607654e6c02a160620c7e1/docs/badge/v2.json)](https://pydantic.dev)
 [![Serious Scaffold Python](https://img.shields.io/badge/serious%20scaffold-python-blue)](https://github.com/serious-scaffold/serious-scaffold-python)
-[![PyPI](https://img.shields.io/pypi/v/{{ package_name }})](https://pypi.org/project/{{ package_name }}/)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/{{ package_name }})](https://pypi.org/project/{{ package_name }}/)
 
-<div align="center">
-  <a href="https://github.com/{{ repo_namespace }}/{{ repo_name }}">
-    <img src="docs/_static/images/logo.png" height=300 alt="{{ project_name }}">
-  </a>
-</div>
+[![{{ project_name }}](docs/_static/images/logo.svg)](https://github.com/{{ repo_namespace }}/{{ repo_name }})
 
-Many efforts have been made to ease the project setup, but most of them are only language-specified basic components. In practice, we have to deal with much more details, especially for team projects. Many commonly used tools and configurations need to be handled properly. Moreover, different people tend to have different favors in various aspects. If you are tired of the inefficient setup process and endless discussion, [Serious Scaffold Python](https://github.com/serious-scaffold/serious-scaffold-python) is here to terminate those for Python Projects.
+Project setup often involves more than just creating a basic project structure. It includes tasks like setting up GitHub Actions or GitLab CI/CD, configuring linters, tests and documentation, and implementing settings and logging modules. If you are tired of this repetitive process, [Serious Scaffold Python](https://github.com/serious-scaffold/serious-scaffold-python) is here to help. Utilizing the power of [`copier`](https://copier.readthedocs.io/), you can generate a new Python project with just one command. Simply answer a few questions, and your project will be fully set up. Additionally, your project can be updated alongside the advancement of the template.
 
 If you find this helpful, please consider [sponsorship](https://github.com/sponsors/{{ author_name }}).
 
-## Features
-
-- Basic Python project structure as a package with tests and documentation.
-- Categorized requirements management with constraints for different environments.
-- [`typer`](https://github.com/tiangolo/typer) for CLI with tests and automatic documentation generation.
-- [`pydantic`](https://github.com/pydantic/pydantic) for [settings](https://pydantic-docs.helpmanual.io/usage/settings/) with tests and documentation as module samples.
-- [`setuptools-scm`](https://github.com/pypa/setuptools_scm/) to extract the version for the package.
-- [`black`](https://github.com/psf/black), [`isort`](https://pycqa.github.io/isort/), [`mypy`](http://www.mypy-lang.org/), [`ruff`](https://github.com/charliermarsh/ruff) and [`toml-sort`](https://github.com/pappasam/toml-sort) as linters.
-- [`pre-commit`](https://github.com/pre-commit/pre-commit) with [general hooks](https://github.com/pre-commit/pre-commit-hooks) and local linters.
-- `Makefile` as the entry point for common actions.
-- VSCode settings with recommended extensions.
-- GitHub workflows for lint, tests, package and documentation preview.
-
-## Quickstart
-
-1. [Install Copier](https://copier.readthedocs.io/en/stable/#installation).
-1. Install the necessary tools for development: `pipenv` and `pre-commit`.
-1. Generate the project with the `copier` command.
-
-   ```
+## 🛠 Features
+
+- **Template Rendering**
+  - Harness [`copier`](https://copier.readthedocs.io/) to initiate projects and enable template updates.
+- **Environment Management**
+  - Utilize [`pipenv`](https://pipenv.pypa.io/) for virtual environment management.
+  - Use containers and system-level `pip` for CI/CD.
+- **Dependency Management**
+  - Manage dependencies categorically with [constraints](https://pip.pypa.io/en/stable/user_guide/#constraints-files) for different environments.
+- **Code Quality Checks**
+  - Incorporate linters including [`black`](https://github.com/psf/black), [`isort`](https://pycqa.github.io/isort/), [`mypy`](http://www.mypy-lang.org/), [`ruff`](https://github.com/charliermarsh/ruff), and [`toml-sort`](https://github.com/pappasam/toml-sort).
+  - Integrate [`pre-commit`](https://github.com/pre-commit/pre-commit) for Git hooks automation.
+- **Tests**
+  - Execute tests with [`pytest`](https://pytest.org/), supplemented by [`coverage`](https://coverage.readthedocs.io) reports and thresholds.
+- **Documentation**
+  - Use [`sphinx`](https://www.sphinx-doc.org/) with the [`furo`](https://pradyunsg.me/furo) theme.
+  - Include [MyPy](https://mypy.readthedocs.io/en/stable/command_line.html?report-generation) and [Coverage](https://coverage.readthedocs.io/en/7.3.0/cmd.html#html-reporting-coverage-html) reports.
+- **Continuous Integration**
+  - Offer a unified `Makefile` for common actions.
+  - Provide configurations for [GitHub Actions](https://docs.github.com/actions) and [GitLab CI/CD](https://docs.gitlab.com/ee/ci/).
+  - Support [Read the Docs](https://readthedocs.org/) integration.
+- **Common Modules**
+  - Use [`typer`](https://typer.tiangolo.com/) for CLI tasks, including tests, documentation, and configuration.
+  - Adopt [`setuptools-scm`](https://github.com/pypa/setuptools_scm/) for versioning via git metadata.
+  - Implement [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) for robust settings management.
+- **Miscellaneous**
+  - Offer VSCode [settings](.vscode/settings.json) and recommended [extensions](.vscode/extensions.json).
+
+## 🔧 Prerequisites
+
+Certain system-level Python applications are needed and it is recommended to use [`pipx`](https://pypa.github.io/pipx/) to install and run them in isolated environments. Refer to pipx's installation instructions [here](https://pypa.github.io/pipx/installation/). Once `pipx` is set up, install the necessary tools using the following commands.
+
+```bash
+# Copier: Template rendering for projects.
+pipx install copier
+
+# Pipenv: Virtual environment and package manager for Python.
+pipx install pipenv
+
+# Pre-commit: Automates Git hooks for code quality checks.
+pipx install pre-commit
+```
+
+## 🚀 Quickstart
+
+1. Generate the project by answering several questions.
+
+   ```bash
    copier copy gh:serious-scaffold/serious-scaffold-python /path/to/project
    ```
 
-1. Initialize the project with the `git` and `make` commands.
+1. Initialize an empty git repository.
 
-   ```
+   ```bash
    cd /path/to/project
    git init
-   git add .
-   make dev
-   make pre-commit
-   git commit -a -m "Init from serious-scaffold-python."
    ```
 
-1. Happy hacking.
+1. Prepare development environment.
 
-## Roadmap
+   ```bash
+   make dev
+   ```
 
-- More detailed documentation for usage.
-- More detailed documentation for features.
-- Add logging module.
-- Refine README template.
-- [Github Automatically generated release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes) integration.
-- [GitHub Dependabot](https://github.com/dependabot) integration.
-- [GitHub issue and pull request templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests).
-- [Gitlab CI/CD](https://docs.gitlab.com/ee/ci/) integration.
-- [Gitlab issue and merge request templates](https://docs.gitlab.com/ee/user/project/description_templates.html).
+1. Commit the initialized project.
 
-## License
+   ```bash
+   git add .
+   git commit -m "Init from serious-scaffold-python."
+   ```
 
-MIT
+1. Initialization Done! Focus on the logical code within `src` folder now.
 
-## Contributing
+## 📜 License
 
-Any suggestions, discussions and bug fixing are all welcome.
+MIT, for more details, see the [LICENSE](LICENSE) file.
diff --git a/docs/_static/images/logo.png b/docs/_static/images/logo.png