A Cookiecutter template for projects using Sphinx
+ tox
+ poetry
. This template was developed thanks to the tutorials by the cookiecutter project along with the instructions provided in HelloCookieCutter1 by Bruce Eckel. The tox
configuration is partly accreditted to Charles Tapley Hoyt's cookiecutter implementation.
First, install the cruft package. Cruft enables keeping projects up-to-date with future updates made to this original template.
pip install cruft
Next, create a project using the monarch-project-template
.
cruft create https://github.com/monarch-initiative/monarch-project-template
This kickstarts an interactive session where you declare the following:
project_name
: Name of the project. [defaults to: Project_X]project_description
: Description of the project. [defaults to: This is the project description.].file_name
: The name of the main python file. [defaults to:main
formain.py
]greeting_recipient
: Just a string that will be displayed when the boilerplate code is invoked. [defaults to:World
as inHello, World!
]full_name
: Your name [defaults to: Author 1]email
: your email [defaults to: author@org.org]license
: Choose one from [MIT
,BSD-3
,GNU GPL v3.0
,Apache Software License 2.0
] [defaults to:MIT
]⚠️ github_token_variable_name_for_doc_deployment
: The github token variable name for document deployment usingSphinx
. [defaults to:GH_TOKEN
]⚠️ github_token_variable_name_for_pypi_deployment
: The github token variable name which aligns with your autogenerated PyPI token for making releases. [defaults to:PYPI_TOKEN
]
⚠️ Do NOT enter actual token here, this is just the variable name that holds the token value in the project repository's Secrets.
This will generate the project folder abiding by the template configuration specified by monarch-project-template
in the cookiecutter.json
file.
The following files and directories are autogenerated in the project:
- Github wokflows:
- For code quality checks (
qc.yml
) - Documentation deployment (
deploy-docs.yml
) - PyPI deployment (
pypi-publish.yml
)
- For code quality checks (
docs
directory withSphinx
configuration files and anindex.rst
file.src
directory structure with theproject_name
directory within it.- Within the
project_name
directory, there are 2 python files:main_file.py
cli.py
forclick
commands.
- Within the
tests
directory with a very basic test.poetry
compatiblepyproject.toml
file containing minimal package requirements.tox.ini
file containing configuration for:coverage-clean
lint
codespell
docstr-coverage
pytest
LICENSE
file based on the choice made during setup.README.md
file containingproject_description
value entered during setup.
Upon creating a new project from the cookiecutter-monarch-ingest
template, there are a few steps you should take to finish setting up the project. First, change into the newly created project.
cd <project_name>
-
Create a new repository on GitHub.
-
Enable GitHub Actions to read and write to the repository (required to deploy the project to GitHub Pages).
- in GitHub, go to Settings -> Action -> General -> Workflow permissions and choose read and write permissions
-
Initialize the local repository and push the code to GitHub. For example:
git init git remote add origin https://github.com/<github_org_name>/<project_name>.git git add -A && git commit -m "Initial commit" git push -u origin main
To finish setting up the project first we'll need to set up a Python development environment. You can either use your system poetry
or install it within a repository virtual environment.
To use you're system poetry
, install poetry
if you haven't already.
pip install poetry
To use poetry within a virtual environmen and install poetry
to the environment use your system Python or install pyenv
and select your python version with pyenv local 3.13
. Then create a virtual environment and install poetry to it. You will also want to add cruft
to the virtual environment to keep updated with this template.
pyenv <python_version>
python -m venv .venv
. .venv/bin/activate
pip install poetry
pip install cruft
Now that we have the basic repository set up and the background dependencies, we can set up the dependencies for the rest of the project. First, we'll use poetry to install project dependencies.
poetry install
Our usage of poetry requires the dynamic versionining plugin.
poetry self add "poetry-dynamic-versioning[plugin]"
Note: If you are using a Linux system and the above doesn't work giving you the following error Invalid PEP 440 version: ...
, you could alternatively run:
poetry add poetry-dynamic-versioning
pre-commit
runs hooks on every commit to automatically point out issues in code such as missing semicolons, trailing whitespace, and debug statements. For more information click here.
poetry run pre-commit install
which will result in the message:
pre-commit installed at .git/hooks/pre-commit
This indicates that you have a successful pre-commit
setup.
poetry run tox
This should run all the bullets mentioned above under the tox
configuration and ideally you should see the following at the end of the run:
coverage-clean: OK (0.20=setup[0.05]+cmd[0.15] seconds)
lint-fix: OK (0.40=setup[0.01]+cmd[0.30,0.09] seconds)
codespell-write: OK (0.20=setup[0.02]+cmd[0.18] seconds)
docstr-coverage: OK (0.29=setup[0.01]+cmd[0.28] seconds)
py: OK (1.29=setup[0.01]+cmd[1.28] seconds)
congratulations :) (2.55 seconds)
And as the last line says: congratulations :)
!! Your project is ready to evolve!
If you have an error running
tox
your python dependencies may be out of sync and you may be able to fix it by runningpoetry lock
and then runningtox
again.
On the command line, type the project_name
. In this example, ABCD
:
poetry run <project_name> run
Should return Hello, **greeting_recipient value chosen during setup**
To run commands within the poetry environment either preface the command with poetry run
, i.e. poetry run /path-to/my-command --options
or open the poetry shell with poetry shell
.
In order to be up-to-date with the template, first check if there is a mismatch between the project's boilerplate code and the template by running:
cruft check
This indicates if there is a difference between the current project's boilerplate code and the latest version of the project template. If the project is up-to-date with the template:
SUCCESS: Good work! Project's cruft is up to date and as clean as possible :).
Otherwise, it will indicate that the project's boilerplate code is not up-to-date by the following:
FAILURE: Project's cruft is out of date! Run `cruft update` to clean this mess up.
For viewing the difference, run cruft diff
. This shows the difference between the project's boilerplate code and the template's latest version.
After running cruft update
, the project's boilerplate code will be updated to the latest version of the template.
For the first time, you'll need to just run the following commands:
poetry build
poetry publish -u YOUR_PYPI_USERNAME -p YOUR_PYPI_PASSWORD
This will release a 0.0.0 version of your project on PyPI.
Use "Trusted Publishers" by PyPI
The documentation desired should be placed in the docs
directory (markdown or reStructured format files).
Let's say the user has 2 more .rst files to add:
- intro.rst
- installation.rst
These two files should be placed in the docs directory and the index.rst
file should be updated to read the following
Welcome to {{project_name}}'s documentation!
=========================================================
.. toctree::
:maxdepth: 2
:caption: Contents:
intro
installation
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
This lets sphinx know to look for theses rst files and generate equivalent HTML files.
Documentation is automatically built and deployed via the github workflow deploy-docs.yml
.
When changes are added to the main branch, this workflow is triggered. For this to work, the user needs to
set-up the github repository of the project to enable documentation from a specific branch. In the Settings
tab
of the repository, click the Pages
section in the left bar. For the Branch
, choose the gh-pages
branch.
The full GitHub Pages documentation can be found here.