diff --git a/.copier-data.yml b/.copier-answers-sample.yml similarity index 92% rename from .copier-data.yml rename to .copier-answers-sample.yml index 71ce318b..caa0bf92 100644 --- a/.copier-data.yml +++ b/.copier-answers-sample.yml @@ -11,7 +11,8 @@ min_py: '3.8' module_name: ss_python organization_name: Serious Scaffold package_name: ss-python -project_description: An evolving Python project template that covers the full development lifecycle. +project_description: An evolving Python project template that covers the full development + lifecycle. project_name: Serious Scaffold Python repo_host_type: github.com repo_name: ss-python diff --git a/.vscode/settings.json b/.vscode/settings.json index cd625805..3ee4edca 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -143,6 +143,7 @@ "min_py", "max_py", "default_py", + "readme_content", "id-token", "pages-build", "release-publish", diff --git a/Makefile b/Makefile index 984dccaf..ac487a83 100644 --- a/Makefile +++ b/Makefile @@ -156,10 +156,10 @@ doc: changelog doc-gen doc-mypy doc-coverage ######################################################################################## consistency: - find . -maxdepth 1 | grep -vE '(\.|\.git|\.copier-data\.yml|template|includes|copier\.yaml|pdm\.lock)$$' | xargs -I {} rm -r {} - copier copy -r HEAD --data-file .copier-data.yml --data repo_host_type=gitlab.com -f . . + find . -maxdepth 1 | grep -vE '(\.|\.git|\.copier-answers-sample\.yml|template|includes|copier\.yaml|pdm\.lock)$$' | xargs -I {} rm -r {} + copier copy -r HEAD --data-file .copier-answers-sample.yml --data repo_host_type=gitlab.com -f . . rm -rf .copier-answers.yml - copier copy -r HEAD --data-file .copier-data.yml -f . . + copier copy -r HEAD --data-file .copier-answers-sample.yml -f . . rm -rf .copier-answers.yml ######################################################################################## diff --git a/copier.yaml b/copier.yaml index 0e08b316..153116a0 100644 --- a/copier.yaml +++ b/copier.yaml @@ -23,8 +23,8 @@ project_name: help: 'Enter the name of the project in CamelCase format:' type: str project_description: - default: A brief description of my project. - help: 'Provide a brief description for the project:' + default: Project brief description. + help: "Provide a concise description to be used in the Python package overview and the introductory paragraph in the README and documentation's index page:" type: str development_status: default: Alpha @@ -170,3 +170,13 @@ default_py: value: '3.12' help: 'Choose the default Python version for development, documentation generation, and package build:' type: str +readme_content: + default: |- + [% if project_name == 'Serious Scaffold Python' -%] + [% from pathjoin("includes", "sample.jinja") import readme_content with context %]{{ readme_content() }} + [%- else -%] + ## A multiline README content here + [%- endif %] + help: "Provide a multiline content to be used in the README and documentation's index page:" + multiline: true + type: str diff --git a/includes/sample.jinja b/includes/sample.jinja new file mode 100644 index 00000000..7ffa8b6e --- /dev/null +++ b/includes/sample.jinja @@ -0,0 +1,93 @@ +[% macro readme_content() -%] +[% from pathjoin("includes", "variable.jinja") import logo_badge with context -%] +[% from pathjoin("includes", "variable.jinja") import logo_badge_url with context -%] +[% from pathjoin("includes", "variable.jinja") import page_url with context -%] +[% from pathjoin("includes", "variable.jinja") import repo_url with context -%] +[![{{ project_name }}](https://{{ page_url() }}/_static/images/logo.svg)](https://{{ repo_url() }}) + +Setting up a project often involves more than just establishing a basic project structure. It involves tasks like integrating GitHub Actions or GitLab CI/CD, configuring lint, test and documentation, as well as implementing settings, logging and other frequently used modules. [Serious Scaffold Python](https://github.com/serious-scaffold/ss-python) streamlines this process. Powered by [`copier`](https://copier.readthedocs.io/), bootstrapping a new Python project can be done with a single command. By answering a few questions, the project will be fully configured and ready for development. Furthermore, the project can be updated alongside the advancement of the template. + +[% if repo_host_type == 'github.com' -%] +If you find this helpful, please consider [sponsorship](https://github.com/sponsors/{{ author_name }}). + +[% endif -%] + +## 🛠️ Features + +- Project setup and template update with [`copier`](https://copier.readthedocs.io/). +- Manage dependencies and virtual environments with [`pdm`](https://pdm-project.org/). +- Version the package using [dynamic SCM tag](https://backend.pdm-project.org/metadata/#read-from-scm-tag-supporting-git-and-hg) with [`pdm-backend`](https://backend.pdm-project.org/). +- Containerization for development and deployment with [dev container](https://containers.dev/). +- Automate dependency updates with [Renovate](https://github.com/renovatebot/renovate). +- Automate Git hooks with [pre-commit hooks](https://github.com/pre-commit/pre-commit-hooks) and [local](https://pre-commit.com/#repository-local-hooks) linters. +- Lint with [`mypy`](http://www.mypy-lang.org/), [`ruff`](https://github.com/charliermarsh/ruff), [`toml-sort`](https://github.com/pappasam/toml-sort) and [`commitlint`](https://commitlint.js.org/). +- Test with [`pytest`](https://pytest.org/) and [`coverage`](https://coverage.readthedocs.io) for threshold and reports. +- Documentation with [`sphinx`](https://www.sphinx-doc.org/), the [`furo`](https://pradyunsg.me/furo) theme, and [mypy](https://mypy.readthedocs.io/en/stable/command_line.html?report-generation)/[coverage](https://coverage.readthedocs.io/en/7.3.0/cmd.html#html-reporting-coverage-html) reports. +- Continuous Integration with [GitHub Actions](https://docs.github.com/actions) and [GitLab CI/CD](https://docs.gitlab.com/ee/ci/). +- Latest stable documentation published to [GitHub](https://docs.github.com/en/pages)/[GitLab](https://docs.gitlab.com/ee/user/project/pages/) Pages. +- [Versioned documentation](https://docs.readthedocs.io/en/stable/versions.html) and [pull request previews](https://docs.readthedocs.io/en/stable/pull-requests.html) with [Read the Docs](https://readthedocs.org/). +- Develop Command Line Interfaces with [`typer`](https://typer.tiangolo.com/). +- Manage configurations with [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/). +- Centralize common actions with a unified Makefile. +- VSCode settings with recommended extensions. + +## 🔧 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 +# PDM: A modern Python package and dependency manager supporting the latest PEP standards. +pipx install pdm +# Pre-commit: Automates Git hooks for code quality checks. +pipx install pre-commit +``` + +## 🚀 Quickstart + +1. Generate the project. + + ```bash + copier copy gh:serious-scaffold/ss-python /path/to/project + ``` + +2. Navigate to the project directory and initialize a git repository. + + ```bash + cd /path/to/project + git init + ``` + +3. Set up the development environment. + + ```bash + make dev + ``` + +4. Commit the initialized project. + + ```bash + git add . + git commit -m "Initialize from serious-scaffold." + ``` + +5. That's it! Feel free to focus on the coding within `src` folder. + +## 🛡 Badge + +Badge for markdown: + +```markdown +{{ logo_badge() }} +``` + +Badge for restructuredtext: + +```restructuredtext +.. image:: {{ logo_badge_url() }} + :target: {{ page_url() }} +``` + +It will look like this: {{ logo_badge() }} +[%- endmacro %] diff --git a/template/.vscode/settings.json b/template/.vscode/settings.json index cd625805..3ee4edca 100644 --- a/template/.vscode/settings.json +++ b/template/.vscode/settings.json @@ -143,6 +143,7 @@ "min_py", "max_py", "default_py", + "readme_content", "id-token", "pages-build", "release-publish", diff --git a/template/Makefile.jinja b/template/Makefile.jinja index a96b93db..1ff1e84e 100644 --- a/template/Makefile.jinja +++ b/template/Makefile.jinja @@ -159,10 +159,10 @@ doc: changelog doc-gen doc-mypy doc-coverage ######################################################################################## consistency: - find . -maxdepth 1 | grep -vE '(\.|\.git|\.copier-data\.yml|template|includes|copier\.yaml|pdm\.lock)$$' | xargs -I {} rm -r {} - copier copy -r HEAD --data-file .copier-data.yml --data repo_host_type=gitlab.com -f . . + find . -maxdepth 1 | grep -vE '(\.|\.git|\.copier-answers-sample\.yml|template|includes|copier\.yaml|pdm\.lock)$$' | xargs -I {} rm -r {} + copier copy -r HEAD --data-file .copier-answers-sample.yml --data repo_host_type=gitlab.com -f . . rm -rf .copier-answers.yml - copier copy -r HEAD --data-file .copier-data.yml -f . . + copier copy -r HEAD --data-file .copier-answers-sample.yml -f . . rm -rf .copier-answers.yml [% endif -%] diff --git a/template/README.md.jinja b/template/README.md.jinja index 458b3a04..42bbac94 100644 --- a/template/README.md.jinja +++ b/template/README.md.jinja @@ -40,93 +40,7 @@ [%- endif %] > Any feedback, comments, suggestions and contributions are welcome! -[![{{ project_name }}](https://{{ page_url() }}/_static/images/logo.svg)](https://{{ repo_url() }}) - -Setting up a project often involves more than just establishing a basic project structure. It involves tasks like integrating GitHub Actions or GitLab CI/CD, configuring lint, test and documentation, as well as implementing settings, logging and other frequently used modules. [Serious Scaffold Python](https://github.com/serious-scaffold/ss-python) streamlines this process. Powered by [`copier`](https://copier.readthedocs.io/), bootstrapping a new Python project can be done with a single command. By answering a few questions, the project will be fully configured and ready for development. Furthermore, the project can be updated alongside the advancement of the template. - -[% if repo_host_type == 'github.com' -%] -If you find this helpful, please consider [sponsorship](https://github.com/sponsors/{{ author_name }}). - -[% endif -%] - -## 🛠️ Features - -- Project setup and template update with [`copier`](https://copier.readthedocs.io/). -- Manage dependencies and virtual environments with [`pdm`](https://pdm-project.org/). -- Version the package using [dynamic SCM tag](https://backend.pdm-project.org/metadata/#read-from-scm-tag-supporting-git-and-hg) with [`pdm-backend`](https://backend.pdm-project.org/). -- Containerization for development and deployment with [dev container](https://containers.dev/). -- Automate dependency updates with [Renovate](https://github.com/renovatebot/renovate). -- Automate Git hooks with [pre-commit hooks](https://github.com/pre-commit/pre-commit-hooks) and [local](https://pre-commit.com/#repository-local-hooks) linters. -- Lint with [`mypy`](http://www.mypy-lang.org/), [`ruff`](https://github.com/charliermarsh/ruff), [`toml-sort`](https://github.com/pappasam/toml-sort) and [`commitlint`](https://commitlint.js.org/). -- Test with [`pytest`](https://pytest.org/) and [`coverage`](https://coverage.readthedocs.io) for threshold and reports. -- Documentation with [`sphinx`](https://www.sphinx-doc.org/), the [`furo`](https://pradyunsg.me/furo) theme, and [mypy](https://mypy.readthedocs.io/en/stable/command_line.html?report-generation)/[coverage](https://coverage.readthedocs.io/en/7.3.0/cmd.html#html-reporting-coverage-html) reports. -- Continuous Integration with [GitHub Actions](https://docs.github.com/actions) and [GitLab CI/CD](https://docs.gitlab.com/ee/ci/). -- Latest stable documentation published to [GitHub](https://docs.github.com/en/pages)/[GitLab](https://docs.gitlab.com/ee/user/project/pages/) Pages. -- [Versioned documentation](https://docs.readthedocs.io/en/stable/versions.html) and [pull request previews](https://docs.readthedocs.io/en/stable/pull-requests.html) with [Read the Docs](https://readthedocs.org/). -- Develop Command Line Interfaces with [`typer`](https://typer.tiangolo.com/). -- Manage configurations with [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/). -- Centralize common actions with a unified Makefile. -- VSCode settings with recommended extensions. - -## 🔧 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 -# PDM: A modern Python package and dependency manager supporting the latest PEP standards. -pipx install pdm -# Pre-commit: Automates Git hooks for code quality checks. -pipx install pre-commit -``` - -## 🚀 Quickstart - -1. Generate the project. - - ```bash - copier copy gh:serious-scaffold/ss-python /path/to/project - ``` - -2. Navigate to the project directory and initialize a git repository. - - ```bash - cd /path/to/project - git init - ``` - -3. Set up the development environment. - - ```bash - make dev - ``` - -4. Commit the initialized project. - - ```bash - git add . - git commit -m "Initialize from serious-scaffold." - ``` - -5. That's it! Feel free to focus on the coding within `src` folder. - -## 🛡 Badge - -Badge for markdown: - -```markdown -{{ logo_badge() }} -``` - -Badge for restructuredtext: - -```restructuredtext -.. image:: {{ logo_badge_url() }} - :target: {{ page_url() }} -``` - -It will look like this: {{ logo_badge() }} +{{ readme_content }} ## 📜 License