Merge branch 'main' into main-github

.bumpversion.cfg

@@ -1,9 +1,7 @@
 [bumpversion]
-current_version = 0.0.0
+current_version = 0.0.2
 message = bump v{current_version} -> v{new_version}
-commit = True
-tag = True
-
-[bumpversion:file:pyproject.toml]
 
 [bumpversion:file:.bumpversion.cfg]
+
+[bumpversion:file:src/init_python_project/cli.py]

.github/workflows/docs.yaml

@@ -24,7 +24,6 @@ jobs:
       - uses: actions/configure-pages@v3
       - run: sudo apt-get update && sudo apt-get install tree
       - run: | # replace symlinks with actual files
-          rm -r src/init_python_project/template src/init_python_project/copier.yaml
           cp -r template src/init_python_project/.
           cp copier.yaml src/init_python_project/.
       - run: | # creating example projects using copier requires a git identity

.gitignore

@@ -10,3 +10,5 @@ __pycache__
 build
 .obsidian
 docs/examples
+src/init_python_project/template
+src/init_python_project/copier.yaml

.pre-commit-config.yaml

@@ -7,6 +7,17 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-added-large-files
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.0.3
+    hooks:
+      - id: prettier
+        types_or: [json, yaml, css, javascript]
+  # black should have the final say on python formatting, so it comes last
+  - repo: https://github.com/psf/black
+    rev: 23.9.1
+    hooks:
+      - id: black
+        name: format code (black)
   - repo: local
     hooks:
       - id: pytest
@@ -17,7 +28,7 @@ repos:
         files: "^template/"
         stages: [push]
   - repo: https://github.com/streetsidesoftware/cspell-cli
-    rev: v7.0.0
+    rev: v7.3.0
     hooks:
       - id: cspell
         name: check spelling (cspell)

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [unreleased]
+
+## [0.0.2]
+
+### Added
+
+-   `init-python-project --version` outputs template version
+
 ## [0.0.1]
 
 Started this template by forking [pypa/sampleproject] and converting it to a copier template.
@@ -45,9 +53,8 @@ An example project (comparable to [pypa/sampleproject]) can be found at [jannism
 
 - trove classifiers (only relevant when publishing to PyPI)
 
-<!-- [unreleased]: https://github.com/jannismain/python-project-template/compare/v0.0.2...HEAD -->
-<!-- [0.0.2]: https://github.com/jannismain/python-project-template/compare/v0.0.1...v0.0.2 -->
-[0.0.1]: https://github.com/jannismain/python-project-template/releases/tag/v0.0.1
-
+[unreleased]: https://github.com/jannismain/python-project-template/compare/v0.0.2...HEAD
+[0.0.2]: https://github.com/jannismain/python-project-template/compare/0.0.1...0.0.2
+[0.0.1]: https://github.com/jannismain/python-project-template/releases/tag/0.0.1
 [pypa/sampleproject]: https://github.com/pypa/sampleproject
 [jannismain/python-project-template-example]: https://github.com/jannismain/python-project-template-example

MANIFEST.in

@@ -0,0 +1,3 @@
+prune template
+prune */__pycache__
+exclude copier.yaml

Makefile

@@ -111,12 +111,19 @@ PKGNAME=init_python_project
 PKGDIR=src/${PKGNAME}
 BUILDDIR?=build/dist
 PYTHON?=python
-build: ## build package
+TEMPLATE_SRC?=./template
+TEMPLATE_DEST?=${PKGDIR}/template
+build: build-clean copy-template ## build package
 	@${PYTHON} -m pip install --upgrade build
 	@${PYTHON} -m build --outdir ${BUILDDIR} .
 install-build: build
 	@pip uninstall -y ${PKGNAME}
 	pip install --force-reinstall ${BUILDDIR}/*.whl
+copy-template:
+	@cp -r ${TEMPLATE_SRC} ${TEMPLATE_DEST}
+	@cp copier.yaml ${PKGDIR}/.
+build-clean: ## remove build artifacts
+	rm -rf ${BUILDDIR} ${PKGDIR}/template ${PKGDIR}/copier.yaml
 
 
 .PHONY: help

README.md

@@ -1,61 +1,68 @@
-# Python Project Template
+<div align=center>
+<h1>Python Project Template</h1>
+
+[![](https://img.shields.io/badge/python-3.11-blue)][sample project]
+[![](https://img.shields.io/badge/Example-Sample_Project-blue)][sample project]
+[![PyPI - Version](https://img.shields.io/pypi/v/init-python-project)][pypi]
+
+</div>
+
+[pypi]: https://pypi.org/project/init-python-project/
+
+<!-- start -->
 
 A customizable template for new Python projects to get you up and running with current best practices faster.
 
 ## Features
 
-- Each project has a [README][] and [CHANGELOG][] file and includes further documentation based on [Material for MkDocs][] or [Sphinx][].
-- [Testing][kb_testing] and [continuous integration][ci] tooling are included from the very beginning
+- Each project has a *README* and *CHANGELOG* file and includes further documentation based on [Material for MkDocs][] or [Sphinx][].
+- *Testing* and *continuous integration* tooling are included from the very beginning
     - Test coverage is collected and displayed as a badge
     - Coverage report is integrated with [Gitlab's coverage report artifact][gitlab coverage report]
 - Projects use [pre-commit][] for sanity checks on each commit or push
 - Projects use bumpversion to increase their version according to [semantic versioning guidelines][semver]
 - Python projects are installable by default and provide a simple command-line interface
 
-[readme]: https://intern.iis.fhg.de/x/I5DPFQ
-[changelog]: https://intern.iis.fhg.de/display/DOCS/Changelog
 [material for mkdocs]: https://squidfunk.github.io/mkdocs-material
 [sphinx]: https://www.sphinx-doc.org
-[ci]: https://intern.iis.fhg.de/x/DK6qG
-[kb_testing]: https://intern.iis.fhg.de/x/DS9SFw
 [gitlab coverage report]: https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportscoverage_report
 [pre-commit]: https://pre-commit.com/
 [semver]: https://semver.org/
 
 Everything comes pre-configured with sensible defaults so you can focus on your implementation and let the template handle the rest.
 
-See this [sample project][] to see how projects generated from this template using default values look like.
+See the [sample project][] to see how projects generated from this template using default values look like.
 
 [sample project]: https://github.com/jannismain/python-project-template-example
 
 ## Getting Started
 
 ### Prerequisites
 
-* [copier][]
+* Python3.11 or newer
 
-*Note: If you have [pipx][] installed (you should, it is good), you can simply use `pipx run copier` out of the box.*
+### Installation
+
+```sh
+pip install init-python-project
+```
+
+*Note: If you have [pipx][] installed (you should, it is good), you can skip this step and instead run it directly using `pipx run init-python-project`*
 
-[copier]: https://github.com/copier-org/copier
 [pipx]: https://pypa.github.io/pipx/
 
 ### Usage
 
 ```console
-copier copy --trust gh:jannismain/python-project-template my_new_project
+init-python-project <name of project>
 ```
 
-*Note: `--trust` is required because the template uses [tasks][] to setup your git repository for you.*
-
-[tasks]: https://github.com/jannismain/python-project-template/blob/main/copier.yaml
-
 <!-- usage-end -->
 
 ## User Guide
 
-The first part of the [user guide][] consists of tutorials on how to answer the template questions for [Your First Project][], what [Next Steps][] there are after your project is created and why the [Project Structure][] looks like it does.
+The first part of the user guide consists of tutorials on how to answer the template questions for [Your First Project][], what [Next Steps][] there are after your project is created and why the [Project Structure][] looks like it does.
 
-[user guide]: https://jannismain.github.io/python-project-template/user-guide/getting-started/
 [your first project]: https://jannismain.github.io/python-project-template/user-guide/first-project
 [next steps]: https://jannismain.github.io/python-project-template/user-guide/first-project
 [project structure]: https://jannismain.github.io/python-project-template/user-guide/project-structure

docs/assets/custom.css

@@ -1,22 +1,22 @@
 /* center mermaid graphs */
 .mermaid {
-    text-align: center;
+  text-align: center;
 }
 
 /* convert emphasized text under images to caption */
-img+em {
-    display: block;
+img + em {
+  display: block;
 }
 
 .md-typeset .caption,
 .md-typeset figcaption {
-    /* same as material's figcaption */
-    font-style: italic;
-    max-width: 24rem;
-    margin: 1em auto 1.5em;
-    text-align: center;
-    display: block;
-    font-size: 0.8rem;
-    /* custom */
-    line-height: 1.2;
+  /* same as material's figcaption */
+  font-style: italic;
+  max-width: 24rem;
+  margin: 1em auto 1.5em;
+  text-align: center;
+  display: block;
+  font-size: 0.8rem;
+  /* custom */
+  line-height: 1.2;
 }

docs/assets/magiclink.css

@@ -13,7 +13,6 @@
   --magiclink-user-icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 448 512"><path d="M224 256c70.7 0 128-57.3 128-128S294.7 0 224 0 96 57.3 96 128s57.3 128 128 128zm89.6 32h-16.7c-22.2 10.2-46.9 16-72.9 16s-50.6-5.8-72.9-16h-16.7C60.2 288 0 348.2 0 422.4V464c0 26.5 21.5 48 48 48h352c26.5 0 48-21.5 48-48v-41.6c0-74.2-60.2-134.4-134.4-134.4z"/></svg>');
 }
 
-
 .md-typeset a[href^="mailto:"]:not(.magiclink-ignore)::before {
   -webkit-mask-image: var(--magiclink-email-icon);
   mask-image: var(--magiclink-email-icon);
@@ -82,7 +81,8 @@
   -webkit-mask-image: var(--magiclink-discussion-icon);
   mask-image: var(--magiclink-discussion-icon);
 }
-.md-typeset .magiclink-repository.magiclink-github:not(.magiclink-ignore)::before,
+.md-typeset
+  .magiclink-repository.magiclink-github:not(.magiclink-ignore)::before,
 .md-typeset .magiclink-mention.magiclink-github:not(.magiclink-ignore)::before {
   -webkit-mask-image: var(--magiclink-github-icon);
   mask-image: var(--magiclink-github-icon);
@@ -92,7 +92,8 @@
   -webkit-mask-image: var(--magiclink-user-icon);
   mask-image: var(--magiclink-user-icon);
 } */
-.md-typeset .magiclink-repository.magiclink-bitbucket:not(.magiclink-ignore)::before {
+.md-typeset
+  .magiclink-repository.magiclink-bitbucket:not(.magiclink-ignore)::before {
   -webkit-mask-image: var(--magiclink-bitbucket-icon);
   mask-image: var(--magiclink-bitbucket-icon);
 }

docs/assets/magiclink.js

@@ -1,5 +1,5 @@
 // remove '@' from github mention magiclink
-let mentions = document.querySelectorAll(".magiclink-gitlab.magiclink-mention")
-mentions.forEach(el => {
-    el.text = el.text.replace("@", "")
+let mentions = document.querySelectorAll(".magiclink-gitlab.magiclink-mention");
+mentions.forEach((el) => {
+  el.text = el.text.replace("@", "");
 });

docs/developer-guide/documentation.md

@@ -6,20 +6,20 @@ This project uses MkDocs with the Material for MkDocs theme.
 
 ??? quote "`mkdocs.yaml` Configuration File"
 
-    {{ includex('mkdocs.yaml', indent=4, lang='yaml') }}
+    {{ includex('mkdocs.yaml', indent=4, code=True) }}
 
 ## Navigation
 
 The navigation is setup using [:octicons-cpu-24:`mkdocs-literate-nav`](https://github.com/oprypin/mkdocs-literate-nav) and managed in the `_nav.md` file:
 
-{{ includex('docs/_nav.md', lang='md') }}
+{{ includex('docs/_nav.md', code=True) }}
 
 ## Macros
 
 [Jinja macros][jinja] are provided by [:octicons-cpu-24:`mkdocs-macros`](https://github.com/fralau/mkdocs_macros_plugin) and can be configured via the `macros.py` file:
 
 ??? quote "`docs/util/macros.py`"
 
-    {{ includex('docs/util/macros.py', indent=4, lang='py') }}
+    {{ includex('docs/util/macros.py', indent=4, code=True) }}
 
 [jinja]: https://jinja.palletsprojects.com/

docs/developer-guide/template/Calculated Variables.md

@@ -4,10 +4,10 @@ They do not appear in the template questionaire and therefore cannot be modified
 
 Calculated template variables are managed in the `context` file within the template:
 
-{{ includex('template/context', lang='jinja', caption=True, raise_errors=True) }}
+{{ includex('template/context', code='jinja', caption=True, raise_errors=True) }}
 
 This context can then be imported using the [jinja import](https://jinja.palletsprojects.com/templates/#import) command.
 
 As an example, this was used in the README template to reuse the `remote_url_pages` and `remote_url_https` URLs, which are calculated from the `remote_url` provided by the user:
 
-{{ includex('template/README.md.jinja', lines=8, lang='jinja', caption=True) }}
+{{ includex('template/README.md.jinja', lines=8, code='jinja', caption=True) }}

docs/developer-guide/template/index.md

@@ -4,6 +4,6 @@ This template is built using [copier][].
 
 The `_subdirectory` is set to *template*, so that the template files are separated from other project files:
 
-{{ includex('copier.yaml', lang='yaml', start_match='_subdirectory', lines=1, caption=True) }}
+{{ includex('copier.yaml', code=True, start_match='_subdirectory', lines=1, caption=True) }}
 
 [copier]: https://github.com/copier-org/copier

docs/index.md

@@ -1,3 +1,3 @@
 # Python Project Template
 
-{{ includex('README.md', start=2, end_match='Getting Started') }}
+{{ includex('README.md', start_match='<!-- start -->', end_match='Getting Started') }}

docs/reference/tooling/git.md

@@ -9,4 +9,18 @@ tags: [Version Control]
 [git]: https://git-scm.com/
 [git-docs]: https://git-scm.com/doc
 
-## git hooks
+
+## [git hooks]
+
+Git provides hooks to run custom code when specific git actions occur. One such action would be a commit, for which git provides the following hooks:
+
+| Hook                 | When                                   | Common use cases               |
+| -------------------- | -------------------------------------- | ------------------------------ |
+| `pre-commit`         | before commit process is started       | linting, style checks, etc.    |
+| `prepare-commit-msg` | before commit message editor is opened | provide default commit message |
+| `commit-msg`         | after commit message is entered        | validate commit message        |
+| `post-commit`        | after commit process is completed      | send notifications             |
+
+These *hooks* are basically just scripts inside the `.git/hooks` directory that are called by git. However, there is also a framework called [pre-commit](../pre-commit), that allows for easy reuse of existing git hooks.
+
+[git hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

docs/reference/tooling/mkdocs.md

@@ -19,7 +19,7 @@ MkDocs is configured in the `mkdocs.yml` file in the root of your project.
 
 ??? quote "`mkdocs.yml`"
 
-    {{ includex("docs/examples/mkdocs/mkdocs.yml", indent=4, lang="yaml") }}
+    {{ includex("docs/examples/mkdocs/mkdocs.yml", indent=4, code=True) }}
 
 ## Extensions
 

docs/reference/tooling/sphinx.md

@@ -22,7 +22,7 @@ Sphinx is configured via a `conf.py` file.
 
 ??? quote "`docs/conf.py`"
 
-    {{ includex('docs/examples/sphinx/docs/conf.py', indent=4, lang='py')}}
+    {{ includex('docs/examples/sphinx/docs/conf.py', indent=4, code=True)}}
 
 See [Sphinx Configuration](https://www.sphinx-doc.org/en/master/usage/configuration.html) for a list of supported options.
 

docs/user-guide/getting-started.md

@@ -1 +1,16 @@
 {{ includex('README.md', start_match='Prerequisites', end_match='<!-- usage-end -->')}}
+
+## Using [copier] directly
+
+```console
+copier copy --trust https://git01.iis.fhg.de/mkj/project-template.git my_new_project
+```
+
+*Note: `--trust` is required because the template uses [tasks][] to setup your git repository for you.*
+
+[tasks]: https://git01.iis.fhg.de/mkj/project-template/-/blob/main/copier.yaml
+
+*Note: If you have [pipx][] installed (you should, it is good), you can simply use `pipx run copier` out of the box.*
+
+[copier]: https://github.com/copier-org/copier
+[pipx]: https://pypa.github.io/pipx/