PhEval Runner Project Template

A Cookiecutter template for projects using MkDocs + tox + poetry. This template was extended from monarch-project-template which 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.

Getting started

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 pheval-runner-template.

cookiecutter https://github.com/yaseminbridges/pheval-runner-template.git

This kickstarts an interactive session where you declare the following:

• project_name: Name of the project. [defaults to: Project_X]
• github_org_name: Name of either the organisation or user. [defaults to: Org_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 for main.py]
• runner_name: The name of the runner. [defaults to: PhEvalToolRunner]
• greeting_recipient: Just a string that will be displayed when the boilerplate code is invoked. [defaults to: World as in Hello, World!]
• full_name: Your name [defaults to: Author 1]
• email: your email [defaults to: [email protected]]
• 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 using Sphinx. [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 pheval-runner-template in the cookiecutter.json file.

What does this do?

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)
• docs directory with MkDocs configuration files and an index.mdfile.
• src directory structure with the project_name directory within it.
  • Within the project_name directory, there are 3 python files:
    • runner.py for implementing plugin runner.
    • main_file.py
    • cli.py for click commands.
• tests directory with a very basic test.
• poetry compatible pyproject.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 containing project_description value entered during setup.

Further setup

Initialise a git repository

git init

Install poetry

Install poetry if you haven't already.

pip install poetry

Install dependencies

poetry install

Set-up pre-commit

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.

Run tox to see if the setup works

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!

Final test to see everything is wired properly

On the command line, type the project_name. In this example, ABCD:

poetry run ABCD 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.

Future updates to the project's boilerplate code

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.

Setting up PyPI release

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.

Push to GitHub

1. Go to [https://github.com/new] and follow the instructions, being sure NOT to add the README.md and .gitignore files (the cookiecutter template will take care of these for you)

2. Add the remote to your local git repository

   git remote add origin https://github.com/my-user-or-organization/ABCD.git
   git branch -M main
   git add .
   git commit -m "first commit"
   git push -u origin main

Automating this via Github Release

Use "Trusted Publishers" by PyPI

Creating documentation

The documentation desired should be placed in the docs directory.

Let's say the user has 2 more .md files to add:

• intro.md
• installation.md

These two files should be placed in the docs directory and the mkdocs.yml file should be updated to read the following

site_name: {{cookiecutter.project_name}}
theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      toggle:
        icon: material/weather-night
        name: Night Mode
    - scheme: slate
      primary: indigo
      toggle:
        icon: material/weather-sunny
        name: Day Mode

markdown_extensions:
  - pymdownx.emoji
  - pymdownx.tasklist
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.highlight
  - mkdocs-click

plugins:
  - search
  - autorefs
  - include_dir_to_nav
  - mkdocstrings:
      enable_inventory: true

watch:
  - src

nav:
  - "index.md"
  - "intro.md"
  - "installation.md"


site_url: https://{{cookiecutter.github_org_name}}.github.io/{{cookiecutter.project_name}}/
repo_url: https://github.com/{{cookiecutter.github_org_name}}/{{cookiecutter.project_name}}
edit_uri: "edit/docs/docs/"

This lets MkDocs know to look for theses md 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.