This is the repository for Antenna's documentation portal.
Documentation is built using MkDocs and deployed using GitHub Pages.
- Install the dependencies - see Quick Setup
- Create a new branch
- Add/modify the files found in the docs folder
- Execute
make preview-docs
to visualize the changes and formatting - Execute
make fix-lint
to ensure proper formatting and linting - Open a Pull Request to submit your changes
Once the Pull Request is reviewed and merged, the new version will be auto-deployed via the configured GitHub Action found here.
This project should be compatible with Python version 3.10 and up.
Current CI and build uses 3.11.
This project uses poetry
as a build tool.
This is a short step by step, no nonsense way of setting things up and start working right away.
For more in depth information, read the other sections below, starting at the Detailed documentation section.
Skip this step if poetry
is already installed.
Installing poetry
with pipx
will make it available to all your other projects, so
you only need to do this once per system (i.e., on your computer, on the MILA cluster, etc.)
- Install pipx
pip install pipx
- Install poetry with pipx:
pipx install poetry
make install
To run the checks:
make fix-lint
To preview the current changes:
make preview-docs
To build the docs locally
make build-docs
To deploy the docs manually (reserved for repository admins)
make deploy-docs
- Install your package :
poetry install
- Initialize pre-commit :
pre-commit install
pre-commit
is installed by default when installing the package using poetry install
.
This is a very lightweight library. It is used for automated and low effort code
quality and code analysis.
-
To use it manually without needing to create an actual commit:
pre-commit run --all-files
-
To create a git
pre-commit
hook, so the tool runs before each commit automatically, execute the following command:pre-commit install
- This is a hands-off approach to code quality, as most of the work will be done automatically each time you create a commit. It will, however, force you to fix the remaining warnings after the automatic fixes.
-
To remove the
pre-commit
hook, executepre-commit clean
-
If you do not want to install
pre-commit
along with your main package, you can usemake install-package
To keep things simple, it is recommended to store all new dependencies as main dependencies, unless you are already familiar with dependency management.
Read and follow the Contributing guidelines