This is a test Python project to experiment with build and integration tools.

Features

• HTML documentation from docstrings with custom style (requires pdoc)
• Package publishing to TestPyPI (requires build)
• Automated code formatting (requires black and isort)
• Code quality auditing (requires flake8 and Flake8-pyproject)
• Static code type checking (requires mypy)
• GitHub workflows for build and release

Disclaimer

This project is not affiliated with GitHub.

This project is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Quickstart

1. Create a new git repository
   • Write a pyproject.toml file
   • Add your logo in a docs directory
   • Add your code in a src directory
   • Add your tests in a tests directory
   • Copy the Makefile and adapt it as needed
   • Copy the .github/workflows directory
   • Copy the static directory
2. Create a new GitHub repository and tune the settings
   • Create a tag protection rule
     • Tag: v*
   • Enable build and deployment for GitHub Pages
     • Source: GitHub Actions
   • Create an environment protection rule
     • Environment: github-pages
     • Deployment tag: v*
   • Create an environment protection rule
     • Environment: testpypi
     • Deployment tag: v*
3. Create a new TestPyPI Trusted Publisher
   • Workflow: release.yml
   • Environment: testpypi
4. Push a first commit to the main branch
   • Set the git remote to the newly created GitHub repository
   • Make sure the Build Action completes successfully
5. Make a first release
   • Tag the main branch as v0.0.0
   • Push the tag to GitHub
   • Create a release from tag v0.0.0
   • Make sure the Release Action completes successfully
6. Create a branch protection rule for main
   • Require a pull request before merging
   • Require status checks to pass before merging
     • Require branches to be up to date before merging
     • Status checks that are required:
       • Code quality
       • Documentation
       • Package distribution
7. Optional improvements
   • Add a .github/CODEOWNERS file
   • Customize general settings
     • Allow merge commits
     • Allow rebase merging
     • Always suggest updating pull request branches
     • Automatically delete head branches
   • Improve the main branch protection rule
     • Require approvals
     • Require conversation resolution before merging
     • Require signed commits
     • Require linear history

References

Useful sources of information:

• GNU Make Manual
• pdoc Documentation
• PyPI Common questions
• Python Packaging User Guide
• Workflow syntax for GitHub Actions

License

The code is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The logo is free art: you can redistribute it and/or modify it under the terms of the CC BY-NC-SA 4.0 License as published by Creative Commons.

You should have received a copy of the GNU General Public License along with this project.

---

Copyright © 2023-2024 Nicolas Canceill