Copier Variables

This document is a maintainer reference for the copier variables used by this template. It distinguishes between variables entered by the user during project creation and variables derived internally by the template, then summarizes where those variables are used in the template files. Its purpose is to make template changes easier to reason about and easier to maintain.

User-supplied Variables

These variables are user-supplied values obtained during the setup of the project. Some of these are are then parsed and turned into derived internal variables.

  • project_name

    • Meaning: Project name as it should appear in documentation and user-facing text.

    • Format: Spaces, upper and lower case allowed.

    • Notes: Typically Buffalo <name>, where <name> is a one-word description of the intent of the project.

    • Used In:

      • CHANGELOG.md.jinja

      • CITATION.cff.jinja

      • docs/workflow_docs_release.md.jinja

      • pyproject.toml.jinja

      • README_HEADING.md.jinja

      • scripts/manual_push_docs.sh.jinja

      • sphinx/source/conf.py.jinja

      • sphinx/source/index.md.jinja

  • project_slug

    • Meaning: Identifier derived from the project name for use in repository, project, and documentation contexts where spaces or special characters are not appropriate.

    • Format: Letters and numbers only; no spaces; PascalCase.

    • Notes:

      • Should be a sanitized form of project_name.

      • Used where a human-readable but filesystem- and URL-friendly project identifier is needed.

    • Used In:

      • CONTRIBUTING.md.jinja

      • docs/workflow_development.md.jinja

      • docs/workflow_docs_release.md.jinja

      • docs/workflow_docs_setup.md.jinja

      • .forgejo/workflows/docs-publish.yaml.jinja

      • .forgejo/workflows/pypi-publish.yaml.jinja

      • pyproject.toml.jinja

      • scripts/manual_push_docs.sh.jinja

      • scripts/manual_push_pypi.sh.jinja

  • package_name

    • Meaning: Python package name for the generated source distribution.

    • Format: Lowercase snake_case valid as a Python module name.

    • Notes:

      • Should be importable as a Python package name.

      • Usually derived from project_name, but converted to snake_case and stripped of invalid characters.

    • Used In:

      • docs/workflow_bump-my-version.md.jinja

      • docs/workflow_release.md.jinja

      • pyproject.toml.jinja

      • scripts/manual_push_pypi.sh.jinja

      • sphinx/source/api/modules.rst.jinja

      • src/[[ package_name ]]/cli/hello_world.py.jinja

      • tests/[[ package_name ]]/test_say_hello.py.jinja

  • description

    • Meaning: Short one-sentence description of the project.

    • Format: Plain text sentence.

    • Notes: Intended for concise summaries such as package metadata, documentation landing pages, and other short descriptive fields.

    • Used In:

      • CONTRIBUTING.md.jinja

      • docs/workflow_development.md.jinja

      • docs/workflow_towncrier_pr.md

      • .forgejo/issue_template/bug.yaml

      • .forgejo/issue_template/feature.yaml

      • .forgejo/issue_template/question.yaml

      • pyproject.toml.jinja

      • SECURITY.md.jinja

      • sphinx/source/conf.py.jinja

      • sphinx/source/index.md.jinja

      • src/[[ package_name ]]/__init__.py.jinja

  • description_long

    • Meaning: Longer description of the project and its purpose.

    • Format: Plain text or Markdown-compatible prose, depending on where it is rendered.

    • Notes:

      • Used where a fuller explanation is appropriate.

      • Should expand on description without becoming excessively detailed.

    • Used In:

      • README_BODY.md.jinja

      • src/[[ package_name ]]/__init__.py.jinja

  • project_version

    • Meaning: Initial version number assigned to the generated project.

    • Format: Semantic version string, MAJOR.MINOR.PATCH.

    • Notes:

      • Usually the starting release version for a new project.

      • Should be valid for Python packaging metadata and release tooling.

      • Will be updated by project as it makes new releases.

    • Used In:

      • CHANGELOG.md.jinja

      • CITATION.cff.jinja

      • pyproject.toml.jinja

      • sphinx/source/conf.py.jinja

      • src/[[ package_name ]]/__init__.py.jinja

  • keywords_csv

    • Meaning: Keywords associated with the project for packaging and discovery.

    • Format: Comma-separated list of keywords.

    • Notes:

      • Entries should be short and descriptive.

      • Keyword can be multiple words, such as “gas dynamics”.

    • Used In:

      • No direct usage.

      • Used to construct keywords.

  • additional_authors

    • Meaning: Additional project authors beyond the default primary author.

    • Format: YAML list of mapping with the following string fields:

      • name: Full display name

      • email: Email address

      • given: Given name(s)

      • family: Family name

      • orcid: Full ORCID URL

    • Notes:

      • Dr. Marshall is included automatically and does not need to be added here.

      • This variable is intended only for additional contributors/authors that should appear in generated metadata or documentation.

    • Used In:

      • No direct usage.

      • Used to construct authors.

  • python_versions_csv

    • Meaning: Supported Python versions for the generated project.

    • Format: Comma-separated list of Python versions in ascending order.

    • Notes: Versions need to be sequential, starting with the oldest supported version and ending with the newest supported version.

    • Used In:

      • No direct usage.

      • Used to construct python_versions and python_min.

  • repo_url

    • Meaning: Public URL of the project source repository.

    • Format: Full URL.

    • Notes: Should point to the main repository homepage.

    • Used In:

      • CITATION.cff.jinja

      • CONTRIBUTING.md.jinja

      • docs/workflow_development.md.jinja

      • .forgejo/issue_template/config.yaml.jinja

      • pyproject.toml.jinja

      • README_BODY.md.jinja

      • README_HEADING.md.jinja

      • sphinx/source/index.md.jinja

  • docs_url

    • Meaning: Public URL where the project documentation will be hosted.

    • Format: Full URL.

    • Notes: Should point to the published documentation site for the generated project.

    • Used In:

      • pyproject.toml.jinja

      • README_HEADING.md.jinja

Fixed Template Variables

These variables are defined in copier.yaml but are not set by the user. They are constant values used in the project.

  • project_created

    • Meaning: Project creation date.

    • Value: Date string in YYYY-MM-DD format

    • Used In:

      • CHANGELOG.md.jinja

  • primary_author

    • Meaning: Primary author information for all projects created from this template.

    • Value: Mapping with the following string fields:

    • Used In:

      • SECURITY.md.jinja

  • codeberg_namespace

    • Meaning: Codeberg name of the organization.

    • Value: “BuffaloHerd”

    • Used In:

      • docs/workflow_docs_release.md.jinja

      • .forgejo/workflows/docs-publish.yaml.jinja

      • scripts/manual_push_docs.sh.jinja

      • SECURITY.md.jinja

  • codeberg_team_email

    • Meaning: Email address for Codeberg organization

    • Value: “buffalo.herd.oss@gmail.com”

    • Used In:

      • CODE_OF_CONDUCT.md.jinja

      • SECURITY.md.jinja

  • license

    • Meaning: License applied to the project.

    • Value: Mapping/object with the following string fields:

      • spdx: “GPL-3.0-only”

      • name: “GNU General Public License v3.0 only”

      • file: “LICENSE.md”

    • Used In:

      • CITATION.cff.jinja

      • CODE_OF_CONDUCT.md.jinja

      • CONTRIBUTING.md.jinja

      • LICENSE.md

      • pyproject.toml.jinja

      • README_HEADING.md.jinja

Derived Internal Variables

These variables are derived from user-supplied variables and are used to setup the project. These might also be created from fixed template variables as well.

  • keywords

    • Meaning: Complete list of keywords for project.

    • Format: YAML list of strings.

    • Notes: Derived from keywords_csv.

    • Used In:

      • CITATION.cff.jinja

      • .forgejo/pull_request_template.md

      • pyproject.toml.jinja

  • authors

    • Meaning: Complete list of authors for project.

    • Format: YAML list of mappings with fields name, email, given, family, and orcid.

    • Notes: Derived from primary_author and additional_authors.

    • Used In:

      • CITATION.cff.jinja

      • pyproject.toml.jinja

      • README_BODY.md.jinja

      • sphinx/source/conf.py.jinja

  • python_versions

    • Meaning: List of supported Python versions.

    • Format: YAML list of semantic version strings.

    • Notes: Derived from python_versions_csv.

    • Used In:

      • .forgejo/workflows/ci.yaml.jinja

      • .forgejo/workflows/docs-check.yaml.jinja

      • .forgejo/workflows/docs-publish.yaml.jinja

      • .forgejo/workflows/pypi-publish.yaml.jinja

      • .forgejo/workflows/towncrier.yaml.jinja

      • pyproject.toml.jinja

      • scripts/run_test_matrix.bat.jinja

      • scripts/run_test_matrix.sh.jinja