Usage¶

Now that the project template has been created, how do we use it?

Configure Environment Variables¶

The first step is to configure the environment variables in the .env file:

GIT_NAME: Your Git username, used for Git configuration.
GIT_EMAIL: Your Git email address, used for Git configuration.
REMOTE_REPO: The remote repository URL for this project.
REPO_USERNAME: Your remote repository username, used for authentication.
REPO_TOKEN: Your remote repository personal access token, used for authentication.

Install Dependencies¶

After configuring these variables, run the install_dep script in the scripts directory:

cd scripts
./install_dep

Note

Make sure to run the script from within the scripts directory, not from the project root or any other directory.

This will install all dependencies required by the project, including the uv package manager, Python packages (via pip), and JavaScript packages (via npm).

Initialize Git¶

Next, run the git_init script:

cd scripts
./git_init

This script initializes a Git repository, sets the remote origin, and installs Husky hooks. These hooks will perform two checks:

A pre-commit check, as defined in .pre-commit-config.yaml
A commit message lint check, as defined in commitlint.config.mjs

Before pushing to the GitHub remote repository for the first time, you must update the GitHub Actions workflow permissions:

Go to your GitHub repository.

Navigate to:

Settings -> Actions -> General -> Workflow permissions

Select “Read and write permissions”
Click “Save”

Once this is done, you can commit and push to the remote repository as usual. Because the GitHub credentials are set in the .env file, you can use the push_to_github script to push your repository to GitHub automatically.

Semantic Release¶

This project uses semantic-release by default to automate versioning and changelog generation based on conventional commit messages.

Features of semantic-release include:

Automatic versioning based on commit history
Automatic changelog generation
Publishing GitHub releases
No need to manually bump version numbers

To trigger a release, simply merge a commit into the main branch that follows the Conventional Commits format. semantic-release will handle the rest via CI.

For configuration details, see the semantic-release documentation.

Publishing to PyPI¶

You can configure PYPI_U and PYPI_P in the .env file, then run the build_and_upload_to_pypi script to upload the package to PyPI. However, this manual method is not recommended.

Instead, the recommended approach is to use automated publishing via CI:

Set author information in ``pyproject.toml``

You must define the following fields in your pyproject.toml file:
```
[project]
name = "your-package-name"
version = "0.0.0"  # This field is managed by semantic-release
description = "Your package description"
authors = [
    { name = "Your Name", email = "your@email.com" }
]
# ... other required metadata
```
Note

You do not need to manually update the version field. It is managed automatically by semantic-release.

Warning

If the authors field is missing or incomplete (missing name or email), the PyPI publishing step will fail during CI.
Configure the PyPI token

In your GitHub repository, navigate to:
```
Settings -> Secrets and variables -> Actions -> New repository secret
```
Create a new secret named PYPI_P and paste your PyPI API token as the value. You can generate the token from your PyPI account under:
```
Account settings -> API tokens
```
Trigger the release

Once the above steps are complete:
- Make a commit that follows the Conventional Commits format.
- Push or merge it into the main branch.
This will trigger the GitHub Actions workflow, which will:
- Let semantic-release determine the next version
- Automatically update the changelog and create a Git tag
- Publish the package to PyPI

Write the Documentation¶

This project uses Sphinx as the documentation generator.

You can run the following command to enable live documentation building and preview while editing:

make livehtml

You can run the make_po script to generate translation template files (.po files) for your documentation.

For more information on Sphinx internationalization (i18n), refer to the official Sphinx guide.

cd scripts/docs
./make_po  # Optional: specify languages with -l, e.g., -l zh_CN -l es

This project also supports documentation hosting via Read the Docs. You can sign in and configure it to enable automatic documentation hosting and updates.

Codecov¶

This project supports Codecov, a popular code coverage reporting tool.

After running your test suite and generating coverage reports, the coverage data can be uploaded to Codecov as part of the CI/CD pipeline.

To enable Codecov integration:

Sign in to Codecov with your GitHub/GitLab account.
Add this repository to your Codecov dashboard.
Generate a Codecov token (optional for public repos).
In your CI environment (e.g., GitHub Actions), upload the coverage report using the official Codecov uploader.
Add a badge to your README to display the current coverage status.

The CI workflow is pre-configured to handle this integration automatically if the coverage report is generated and uploaded correctly.