Project layout

This section provides an overview of the key paths in your Salt extension project.

.copier-answers.yml

Stores Copier-specific data, including answers to template questions, the template’s source URI, and the last version the project was updated to.

Do not edit manually. To change your answers, use copier update --trust. To avoid updating the template version, pass the current version in vcs-ref.

CHANGELOG.md

Contains the project’s changelog. Update this file using towncrier instead of manually.

README.md

Provides a brief project overview and developer information. Includes a note about user documentation and, if docs_url was set, a link to the hosted documentation.

noxfile.py

Defines nox sessions for running tests, building documentation, and linting code.

pyproject.toml

Holds project metadata, package dependencies and configuration for tools used in the project’s lifecycle.

.github

Contains GitHub-related configurations and workflows. This directory is only present if your source_url is on GitHub.

.github/workflows

Houses GitHub Actions workflows.

.github/workflows/ci.yml

A meta-workflow that triggers other workflows based on inputs.

Important

Only present when workflows == enhanced.

.github/workflows/pr.yml

Handles workflows for Pull Requests and pushes to the main branch. Depending on workflows, it either calls centralized workflows in salt-extensions/central-artifacts or local workflows in ci.yml.

.github/workflows/tag.yml

Triggered by tag pushes for tags beginning with v. Similar to pr.yml, it either calls centralized workflows or local ones in ci.yml.

changelog

Directory containing news fragments for towncrier. Also includes the default version-specific changelog template in changelog/.template.jinja.

docs

Root directory for documentation-related files.

docs/conf.py

Contains Sphinx configuration and plugins.

docs/index.rst

Homepage for the documentation, (indirectly) linking to all other documentation files.

Hint

If your project includes a utils directory, manually add the corresponding documentation here (not handled by the Copier template or the pre-commit hook).

docs/ref

Directory containing autogenerated module documentation. Typically does not require manual updates, but can be used for custom documents, like a configuration reference.

docs/topics

Intended to hold high-level guides related to your Salt extension, such as Configuration. By default, includes an Installation guide.

src

Root directory for your Salt extension’s package.

tests

Root directory for Pytest-based test modules.

tests/conftest.py

Provides default fixtures and basic test setup.

tests/functional

Contains functional tests.

tests/functional/conftest.py

Provides default fixtures for functional tests.

tests/integration

Contains integration tests.

tests/integration/conftest.py

Provides default fixtures for integration tests.

tests/unit

Contains unit tests.

tests/unit/conftest.py

Provides default fixtures for unit tests.