Pixi Project

A template for creating Python projects with modern development practices.

Features

• Packaging and dependency management with Pixi
• Test automation with Nox
• Linting with pre-commit and Ruff
• Continuous integration with GitHub Actions
• Documentation with Sphinx, MyST, and Read the Docs using the furo theme
• Automated uploads to PyPI and TestPyPI
• Automated release notes with Release Drafter
• Automated dependency updates with Dependabot
• Code formatting with Ruff
• Testing with pytest
• Code coverage with Coverage.py
• Coverage reporting with Codecov
• Command-line interface with Typer
• Static type-checking with mypy
• Runtime type-checking with Typeguard
• Automated Python syntax upgrades with pyupgrade
• Security audit with Bandit and pip-audit
• Check documentation examples with xdoctest
• Generate API documentation with autodoc and napoleon

• Manage project labels with GitHub Labeler

Requirements

• Python >= 3.11
• Pixi package manager

Installation

For Development

1. Clone the repository:

git clone https://github.com/eLearningHub/academic-project-template.git
cd academic-project-template

2. Install Pixi if you haven't already:

curl -fsSL https://pixi.sh/install.sh | bash

3. Install dependencies using Pixi:

pixi install

4. Install development dependencies:

pixi run install-dev

5. Install pre-commit hooks:

pixi run pre-commit install

6. (Optional) Install Quarto extensions if needed:

pixi run install-quarto-extensions

Important: When using Pixi, always add dependencies with pixi add commands instead of editing pyproject.toml directly. Use pixi add [package] for dependencies (pixi add --pypi [package] for packages only on PyPI). Pixi will automatically update the pyproject.toml file with the appropriate configuration. See pixi_setup.md for more details.

Documentation

To build the documentation locally:

Using Quarto

pixi run docs

Using Sphinx

pixi run sdocs

The Sphinx documentation will be available in the docs/_build directory.

Development Tasks

The project includes several predefined tasks that can be run using Pixi:

# Run tests
pixi run test

# Format code
pixi run format

# Lint code
pixi run lint

# Type check
pixi run mypy

# Build documentation
pixi run docs

# Run the CLI
pixi run cli

Using Nox

For additional isolation, you can use Nox:

# Install Nox
pip install nox

# Run tests
nox -s tests

# Lint and check formatting (ruff)
nox -s lint

# Type check
nox -s mypy

# Build documentation
nox -s docs

Project Structure

academic-project-template/
├── src/
│   └── pixi_project/
│       ├── __init__.py
│       └── cli.py
├── tests/
│   ├── __init__.py
│   └── test_cli.py
├── docs/
│   ├── conf.py
│   ├── index.md
│   └── ...
├── .github/
│   └── workflows/
│       ├── tests.yml
│       ├── lint.yml
│       └── release.yml
├── pyproject.toml
├── noxfile.py
├── .pre-commit-config.yaml
├── .readthedocs.yaml
├── CODE_OF_CONDUCT.md
├── CHANGELOG.md
├── pixi_setup.md
└── README.md

License

This project is licensed under the MIT License, as declared in pyproject.toml.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Acknowledgements

We extend our heartfelt gratitude to the authors of Nerfies for generously open-sourcing their website template, which inspired this project's design and functionality.

We also sincerely thank Michael J. Mahoney for creating and sharing the invaluable Quarto template for arXiv preprints.

Contact

Behzad Samadi