From 3214bf0c5e724789cf36c74dc37f95d5f04994f4 Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Mon, 25 Sep 2023 18:04:26 +0200 Subject: [PATCH 01/13] doc(ops): add release instructions --- .vscode/terms.txt | 1 + docs/developer-guide/release.md | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+) create mode 100644 docs/developer-guide/release.md diff --git a/.vscode/terms.txt b/.vscode/terms.txt index 97b077da..e503d29c 100644 --- a/.vscode/terms.txt +++ b/.vscode/terms.txt @@ -6,6 +6,7 @@ cyclomatic docstrings Docutils endfor +fraunhofer Furo gitfile gitlab diff --git a/docs/developer-guide/release.md b/docs/developer-guide/release.md new file mode 100644 index 00000000..0ffdc051 --- /dev/null +++ b/docs/developer-guide/release.md @@ -0,0 +1,32 @@ +# Releasing a new version + +As this repository is hosted on three different remotes to reach different target audiences ([Fraunhofer IIS internal](https://git01.iis.fhg.de), [FHG internal](https://gitlab.cc-asp.fraunhofer.de) and [public](https://github.com/jannismain/python-project-template)), it is convenient to have their respective main branches all available under different names in your local repository: + +``` +git remote add origin git@git01.iis.fhg.de:mkj/project-template.git +git checkout main +git remote add fhg git@gitlab.cc-asp.fraunhofer.de:mkj/project-template.git +git remote add github git@github.com:jannismain/python-project-template.git +git branch --set-upstream-to=fhg/main main-fhg +git branch --set-upstream-to=github/main main-github +``` + +Each of those remotes host a version of the project template with links updated to point to that remote. Therefore, updates cannot be simply pushed to those remotes but need to be merged into their main branches, so that the platform-specific changes remain intact. + +With those preparations in place, a new release can be created like this: + +1. Commit everything that should be part of the release to be `main` branch of the IIS-internal version of the repository. That includes updating the CHANGELOG and bumping the version number. +2. Merge those changes into the `main` branches of the fhg and public remotes. + + ``` + git co main-fhg + git merge main --ff-only --ff + git co main-github + git merge main --ff-only --ff + ``` + +3. Trigger the release process on the public `main` branch + + ``` + make release + ``` From f9a032228e4ace8ae5d2f9daa00d0559929a3ea2 Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Mon, 25 Sep 2023 18:15:19 +0200 Subject: [PATCH 02/13] template(ci): gitlab-fhg jobs include asprunner tag --- .vscode/terms.txt | 1 + CHANGELOG.md | 4 ++++ ...te.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja | 5 ++++- 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.vscode/terms.txt b/.vscode/terms.txt index e503d29c..abc0d2ef 100644 --- a/.vscode/terms.txt +++ b/.vscode/terms.txt @@ -1,3 +1,4 @@ +asprunner automodule BUILDDIR bumpversion diff --git a/CHANGELOG.md b/CHANGELOG.md index 891d01c5..3bc9a04e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [unreleased] +### Added + +- automatically assign `asprunner` tag in GitLab CI configuration intended for `gitlab-fhg` remote. + ## [0.0.5] - 2023-09-25 ### Fixed diff --git a/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja b/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja index f33e6eeb..d34a926e 100644 --- a/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja +++ b/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja @@ -1,4 +1,7 @@ -image: python:latest +default: + image: python:latest + {% if remote=='gitlab-fhg' -%} + tags: [asprunner]{% endif %} test: cache: # reuse venv in subsequent jobs From b0841471160c7668a7477564c5cc5867d0d8a180 Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Mon, 25 Sep 2023 18:56:45 +0200 Subject: [PATCH 03/13] fix: whitespace issue in gitlab ci config --- ...mote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja b/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja index d34a926e..31746d44 100644 --- a/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja +++ b/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja @@ -1,6 +1,5 @@ default: - image: python:latest - {% if remote=='gitlab-fhg' -%} + image: python:latest{% if remote=='gitlab-fhg' %} tags: [asprunner]{% endif %} test: From 21c7e779eab712ce7d1bc33b26aeff05c64e55a6 Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Tue, 26 Sep 2023 13:18:18 +0200 Subject: [PATCH 04/13] template(ci): artifacts expire after 1 week most recent artifacts are always kept unless otherwise configured --- CHANGELOG.md | 1 + ...emote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja | 2 ++ 2 files changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3bc9a04e..090eb3db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - automatically assign `asprunner` tag in GitLab CI configuration intended for `gitlab-fhg` remote. +- GitLab CI artifacts are set to expire after 1 week to reduce overall storage usage (most recent artifact is kept) ## [0.0.5] - 2023-09-25 diff --git a/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja b/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja index 31746d44..0925d683 100644 --- a/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja +++ b/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja @@ -37,6 +37,7 @@ test: - build/coverage - build/badges - env/ + expire_in: 1w # most recent artifact is always kept {% if docs == 'sphinx' -%} include: docs/.gitlab/docs.yml @@ -67,3 +68,4 @@ pages: artifacts: paths: - public + expire_in: 1w From 1b7a9b5cd53ee446a09718679953c4406b3c09a0 Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Tue, 26 Sep 2023 13:28:38 +0200 Subject: [PATCH 05/13] test: fix github remote test was not running into test assertions for github remotes --- tests/test_template.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_template.py b/tests/test_template.py index 5f54bbe7..02b53943 100644 --- a/tests/test_template.py +++ b/tests/test_template.py @@ -170,7 +170,7 @@ def test_remote_option(tmp_path: Path, remote: str): readme_template_url = (tmp_path / "README.md").open().readlines()[-1].strip() - if remote == "gitlab": + if remote == "github": assert remote_url == f"git@github.com:{user_name}/wonderful-project.git" assert (tmp_path / ".github").is_dir() assert "github.com" in readme_template_url From 891d5b0020edfd95b23e706aabb3c42f796d53c6 Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Tue, 26 Sep 2023 13:58:47 +0200 Subject: [PATCH 06/13] ops(ci): add gitlabci-lint pre-commit hook --- .gitlab-ci.yml | 3 ++- .pre-commit-config.yaml | 7 +++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 9c8853eb..bb11d00a 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,4 +1,5 @@ -image: python +default: + image: python variables: GIT_DEPTH: 0 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 88a2b1a2..3240b7d6 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -41,3 +41,10 @@ repos: --config, .vscode/cspell.json, ] + - repo: https://github.com/bjd2385/pre-commit-gitlabci-lint + rev: v1.3.0 + hooks: + - id: gitlabci-lint + args: ["-p", "46207681"] # project id is required, but any will do + entry: env GITLAB_TOKEN=w8i5Q1CaEpF57cqxezvG gitlabci-lint + files: "^\\.gitlab-ci\\.yml$" From dcce94959470ad87c39ae22267e58a2e1587ee47 Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Tue, 26 Sep 2023 13:59:49 +0200 Subject: [PATCH 07/13] template(ci): add pre-commit hook to lint gitlab ci --- CHANGELOG.md | 1 + ...if precommit %}.pre-commit-config.yaml{% endif %}.jinja | 7 +++++++ 2 files changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 090eb3db..d60b4f73 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - automatically assign `asprunner` tag in GitLab CI configuration intended for `gitlab-fhg` remote. - GitLab CI artifacts are set to expire after 1 week to reduce overall storage usage (most recent artifact is kept) +- pre-commit hook that lints `.gitlab-ci.yml` and prevents committing a faulty config ## [0.0.5] - 2023-09-25 diff --git a/template/{% if precommit %}.pre-commit-config.yaml{% endif %}.jinja b/template/{% if precommit %}.pre-commit-config.yaml{% endif %}.jinja index f1c504fb..89934f16 100644 --- a/template/{% if precommit %}.pre-commit-config.yaml{% endif %}.jinja +++ b/template/{% if precommit %}.pre-commit-config.yaml{% endif %}.jinja @@ -9,3 +9,10 @@ repos: exclude: .*\.dat - id: check-yaml - id: check-added-large-files + - repo: https://github.com/bjd2385/pre-commit-gitlabci-lint + rev: v1.3.0 + hooks: + - id: gitlabci-lint + args: ["-p", "46207681"] # project id is required, but any will do + entry: env GITLAB_TOKEN=w8i5Q1CaEpF57cqxezvG gitlabci-lint + files: "^\\.gitlab-ci\\.yml$" From d2fad15a49f8cceceaad5c763f47e6ddfff0cf70 Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Wed, 27 Sep 2023 08:50:53 +0200 Subject: [PATCH 08/13] template: add gitlabci-lint pre-commit hook only include for gitlab remotes with mkdocs for now (see #26) --- .vscode/terms.txt | 1 + CHANGELOG.md | 1 + ...t %}.pre-commit-config.yaml{% endif %}.jinja | 4 ++-- tests/test_template.py | 17 ++++++++++++++++- 4 files changed, 20 insertions(+), 3 deletions(-) diff --git a/.vscode/terms.txt b/.vscode/terms.txt index abc0d2ef..18584563 100644 --- a/.vscode/terms.txt +++ b/.vscode/terms.txt @@ -11,6 +11,7 @@ fraunhofer Furo gitfile gitlab +gitlabci gitmoji glab includex diff --git a/CHANGELOG.md b/CHANGELOG.md index d60b4f73..2a065db5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - automatically assign `asprunner` tag in GitLab CI configuration intended for `gitlab-fhg` remote. - GitLab CI artifacts are set to expire after 1 week to reduce overall storage usage (most recent artifact is kept) - pre-commit hook that lints `.gitlab-ci.yml` and prevents committing a faulty config + - available for projects with gitlab remote using mkdocs ## [0.0.5] - 2023-09-25 diff --git a/template/{% if precommit %}.pre-commit-config.yaml{% endif %}.jinja b/template/{% if precommit %}.pre-commit-config.yaml{% endif %}.jinja index 89934f16..b3dc0e0d 100644 --- a/template/{% if precommit %}.pre-commit-config.yaml{% endif %}.jinja +++ b/template/{% if precommit %}.pre-commit-config.yaml{% endif %}.jinja @@ -8,11 +8,11 @@ repos: - id: end-of-file-fixer exclude: .*\.dat - id: check-yaml - - id: check-added-large-files + - id: check-added-large-files{% if remote.startswith('gitlab') and docs != 'sphinx' %} - repo: https://github.com/bjd2385/pre-commit-gitlabci-lint rev: v1.3.0 hooks: - id: gitlabci-lint args: ["-p", "46207681"] # project id is required, but any will do entry: env GITLAB_TOKEN=w8i5Q1CaEpF57cqxezvG gitlabci-lint - files: "^\\.gitlab-ci\\.yml$" + files: "^\\.gitlab-ci\\.yml$"{% endif %} diff --git a/tests/test_template.py b/tests/test_template.py index 02b53943..758f7be5 100644 --- a/tests/test_template.py +++ b/tests/test_template.py @@ -28,6 +28,11 @@ ) +def get_precommit_hooks(pre_commit_config_path: Path) -> list[str]: + pre_commit_config = yaml.safe_load(pre_commit_config_path.open()) + return [hook["id"] for repo in pre_commit_config["repos"] for hook in repo["hooks"]] + + @pytest.fixture def venv(tmp_path): """Create virtual environment in subdirectory of tmp_path.""" @@ -83,6 +88,14 @@ def test_template_generation( fp_precommit_config = tmp_path / ".pre-commit-config.yaml" assert fp_precommit_config.is_file() == precommit + if precommit: + # gitlabci-lint incompatible with sphinx, as ci job is imported from docs/.gitlab/docs.yml + # so it is currently only included for projects using mkdocs with gitlab + if remote.startswith("gitlab") and docs != "sphinx": + assert "gitlabci-lint" in get_precommit_hooks(fp_precommit_config) + else: + assert "gitlabci-lint" not in get_precommit_hooks(fp_precommit_config) + fp_git = tmp_path / ".git" assert fp_git.is_dir(), "new projects should be git repositories" @@ -175,7 +188,9 @@ def test_remote_option(tmp_path: Path, remote: str): assert (tmp_path / ".github").is_dir() assert "github.com" in readme_template_url if remote.startswith("gitlab"): - assert (tmp_path / ".gitlab-ci.yml").is_file() + gitlab_ci_yml = tmp_path / ".gitlab-ci.yml" + assert gitlab_ci_yml.is_file() + check_call(["pre-commit", "run", "--all-files", "gitlabci-lint"], cwd=str(tmp_path)) if remote.endswith("iis"): assert remote_url == f"git@git01.iis.fhg.de:{user_name}/wonderful-project.git" assert "git01.iis.fhg.de" in readme_template_url From caa24e42c14285258b8e56110763522fb27e148e Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Wed, 27 Sep 2023 08:58:47 +0200 Subject: [PATCH 09/13] fix(template): mkdocs projects building docs in ci doc requirements are now installed again --- CHANGELOG.md | 4 ++++ ...te.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja | 5 +++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2a065db5..60aac0f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - pre-commit hook that lints `.gitlab-ci.yml` and prevents committing a faulty config - available for projects with gitlab remote using mkdocs +### Fixed + +- Gitlab projects using mkdocs didn't install doc requirements during CI + ## [0.0.5] - 2023-09-25 ### Fixed diff --git a/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja b/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja index 0925d683..d741a94c 100644 --- a/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja +++ b/template/{% if remote.startswith('gitlab') %}.gitlab-ci.yml{% endif %}.jinja @@ -42,10 +42,11 @@ test: {% if docs == 'sphinx' -%} include: docs/.gitlab/docs.yml -{% elif docs == 'mkdocs' %} +{% elif docs == 'mkdocs' -%} docs: script: - mkdocs build --clean --site-dir build/docs + - pip install -r docs/requirements.txt + - mkdocs build --clean --site-dir build/docs artifacts: paths: - build/docs From d47324a1a7be1b1525896f87b87d15aceeccc7f4 Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Wed, 27 Sep 2023 10:16:14 +0200 Subject: [PATCH 10/13] test: remove redundant check for doc requirements --- tests/test_template.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/tests/test_template.py b/tests/test_template.py index 758f7be5..2bb0f42d 100644 --- a/tests/test_template.py +++ b/tests/test_template.py @@ -221,8 +221,6 @@ def test_docs_option(venv: VirtualEnvironment, tmp_path: Path, docs: str): elif docs == "sphinx": fp_sphinx_makefile = root / "docs" / "Makefile" assert fp_sphinx_makefile.is_file(), "sphinx Makefile should exist" - fp_sphinx_requirements = root / "docs" / "requirements.txt" - assert fp_sphinx_requirements.is_file(), "sphinx requirements file should exist" fp_sphinx_ci_job = root / "docs" / ".gitlab" / "docs.yml" assert fp_sphinx_ci_job.is_file(), "sphinx ci job should exist" From 7090af94c6885aff6b92b991bc8769529b6ca7b1 Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Wed, 27 Sep 2023 10:39:34 +0200 Subject: [PATCH 11/13] template(doc): fix docstring parsing replace sphinx-autodoc2 with sphinx-autoapi as it supports google-style docstrings and provides the same convenience as autodoc2 --- .vscode/terms.txt | 2 ++ CHANGELOG.md | 5 ++++ .../conf.py.jinja | 30 +++++++------------ .../index.md | 1 - .../requirements.txt | 2 +- 5 files changed, 18 insertions(+), 22 deletions(-) diff --git a/.vscode/terms.txt b/.vscode/terms.txt index 18584563..af0a721e 100644 --- a/.vscode/terms.txt +++ b/.vscode/terms.txt @@ -1,4 +1,6 @@ asprunner +autoapi +autodoc automodule BUILDDIR bumpversion diff --git a/CHANGELOG.md b/CHANGELOG.md index 60aac0f3..51faf801 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,9 +14,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - pre-commit hook that lints `.gitlab-ci.yml` and prevents committing a faulty config - available for projects with gitlab remote using mkdocs +### Changed + +- replace sphinx-autodoc2 with sphinx-autoapi for better google-style docstring support + ### Fixed - Gitlab projects using mkdocs didn't install doc requirements during CI +- docstring argument section not parsed correctly ## [0.0.5] - 2023-09-25 diff --git a/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/conf.py.jinja b/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/conf.py.jinja index 949edaf2..89f150de 100644 --- a/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/conf.py.jinja +++ b/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/conf.py.jinja @@ -38,25 +38,15 @@ myst_enable_extensions = [ "colon_fence", # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#markdown-figures ] -# -- Options for sphinx-autodoc2 --------------------------------------------- -# https://sphinx-autodoc2.readthedocs.io/en/latest/config.html +# -- Options for sphinx-autoapi ---------------------------------------------- +# https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html -extensions += ["autodoc2"] # https://sphinx-autodoc2.readthedocs.io/ - -autodoc2_output_dir = "apidocs" -autodoc2_packages = [ - "../src/{{package_name}}", +extensions += [ + "sphinx.ext.napoleon", # required to parse google-style docstrings + "sphinx.ext.autodoc", # required to parse typehints + "autoapi.extension", ] -autodoc2_render_plugin = "md" -{% raw %} -autodoc2_index_template = """ -API Documentation -================= - -.. toctree:: - :titlesonly: -{% for package in top_level %} - {{ package }} -{%- endfor %} -""" -{% endraw -%} +autoapi_dirs = ["../src/{{package_name}}"] + +# https://sphinx-autoapi.readthedocs.io/en/latest/how_to.html#how-to-include-type-annotations-as-types-in-rendered-docstrings +autodoc_typehints = "description" diff --git a/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/index.md b/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/index.md index ec0fab19..7c83c926 100644 --- a/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/index.md +++ b/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/index.md @@ -11,5 +11,4 @@ hide-toc: true :hidden: changelog -apidocs/index ``` diff --git a/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/requirements.txt b/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/requirements.txt index 4df05720..06f7877e 100644 --- a/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/requirements.txt +++ b/template/{% if docs == 'sphinx' and docs_template=='none' %}docs{% endif %}/requirements.txt @@ -1,5 +1,5 @@ sphinx furo myst_parser -sphinx-autodoc2 +sphinx-autoapi sphinx-autobuild From f8f8e67e280827e09127b3023c3971fee4b6b47a Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Thu, 28 Sep 2023 15:19:20 +0200 Subject: [PATCH 12/13] ops: add `make link-template` command --- Makefile | 6 +++++- docs/developer-guide/template-in-package.md | 15 +++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 docs/developer-guide/template-in-package.md diff --git a/Makefile b/Makefile index 32e80b99..bb85493a 100644 --- a/Makefile +++ b/Makefile @@ -18,7 +18,7 @@ build/examples/gitlab_fhg: INIT_PYTHON_PROJECT_ARGS+=--remote=gitlab-fhg --remot build/examples/gitlab_iis: INIT_PYTHON_PROJECT_ARGS+=--remote=gitlab-iis --remote-url=git@git01.iis.fhg.de:mkj/sample-project.git build/examples/gitlab_iis_sphinx: INIT_PYTHON_PROJECT_ARGS+=--remote=gitlab-iis --remote-url=git@git01.iis.fhg.de:mkj/sample-project-sphinx.git --docs=sphinx -$(PUBLISHED_EXAMPLES): uncopy-template copy-template +$(PUBLISHED_EXAMPLES): uncopy-template link-template @echo "Recreating '$@'..." @rm -rf "$@" && mkdir -p "$@" init-python-project "$@" ${INIT_PYTHON_PROJECT_ARGS} --defaults --yes --verbose @@ -124,6 +124,10 @@ copy-template: @cp copier.yaml ${PKGDIR}/. uncopy-template: @rm -rf ${TEMPLATE_DEST} ${PKGDIR}/copier.yaml +link-template: + @cd ${PKGDIR} &&\ + ln -s ../../${TEMPLATE_SRC} template &&\ + ln -s ../../copier.yaml copier.yaml build-clean: uncopy-template ## remove build artifacts @rm -rf ${BUILDDIR} diff --git a/docs/developer-guide/template-in-package.md b/docs/developer-guide/template-in-package.md new file mode 100644 index 00000000..498e29fb --- /dev/null +++ b/docs/developer-guide/template-in-package.md @@ -0,0 +1,15 @@ +# Template in Package + +## Summary + +- use `make copy-template` before building a package. +- use `make link-template` during development with an in-place installation. + +## Explanation + +Copier templates require a `copier.yaml` in the root of the git project in order to be discovered during `copier copy gh:jannismain/python-project-template`. + +However, for distribution of the template as a Python package, the template files need to be part of the Python package in `src/init_python_project/`. +So when building a package using `make build`, the template files are copied into the package using `make copy-template`. + +During development, a copy is impractical, as changes to the template are not picked up by `init-python-project`, which still uses the (now out-of-date) copy inside the package. For this reason, it is useful to *link* the template into the package using `make link-template`. Those symbolic links are not supported when building a Python package, so they are replaced the next time a package is created. From 09c0a203ffc6d68e71fe55c1f96ef3c8e46dec6e Mon Sep 17 00:00:00 2001 From: Jannis Mainczyk Date: Thu, 28 Sep 2023 15:21:46 +0200 Subject: [PATCH 13/13] fix: adding back missing LICENSE information --- .vscode/terms.txt | 2 ++ DEPENDENCIES | 19 +++++++++++++++++++ LICENSE | 20 ++++++++++++++++++++ pyproject.toml | 1 + 4 files changed, 42 insertions(+) create mode 100644 DEPENDENCIES create mode 100644 LICENSE diff --git a/.vscode/terms.txt b/.vscode/terms.txt index af0a721e..5c223833 100644 --- a/.vscode/terms.txt +++ b/.vscode/terms.txt @@ -17,10 +17,12 @@ gitlabci gitmoji glab includex +Jannis jannismain jimustafa jinja magiclink +Mainczyk mkdocs mkdocstrings myst diff --git a/DEPENDENCIES b/DEPENDENCIES new file mode 100644 index 00000000..c74aceda --- /dev/null +++ b/DEPENDENCIES @@ -0,0 +1,19 @@ +Copyright (c) 2016 The Python Packaging Authority (PyPA) + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..5bf17a11 --- /dev/null +++ b/LICENSE @@ -0,0 +1,20 @@ +The MIT License (MIT) +Copyright (c) 2023 Jannis Mainczyk + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, +DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE +OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/pyproject.toml b/pyproject.toml index d7dbe85e..93b8d987 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,6 +11,7 @@ authors = [{ name = "Jannis Mainczyk", email = "jmainczyk@gmail.com" }] maintainers = [{ name = "Jannis Mainczyk", email = "jmainczyk@gmail.com" }] dependencies = ["copier", "typer[all]"] dynamic = ["version"] +license = { file = "LICENSE", type = "MIT" } [tool.setuptools_scm] fallback_version = "0.0.0"