Contributing

Please refer to Project Jupyter’s Code of Conduct for guidelines on fostering a friendly and collaborative environment.

Setting up a local development environment¶

This project uses the Python package manager uv. Below are the steps to set up a local development environment.

1. Clone this repository

git clone https://github.com/2i2c-org/jupyterhub-cost-monitoring.git

1. Install uv

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install project dependencies and source the .venv environment

   uv sync
   source .venv/bin/activate

3. Authenticate with AWS credentials (requires AWS CLI installation). This example uses a session token from an MFA code associated with an MFA device:

export AWS_PROFILE=<aws-profile-name>
export CLUSTER_NAME=<cluster-name>
export MFA_DEVICE_ID=<mfa-device-id>
aws sts get-session-token --serial-number $MFA_DEVICE_ID --profile $AWS_PROFILE --token-code ******

1. Run the FastAPI web server

   cd src/jupyterhub_cost_monitoring
   fastapi dev app.py --port 8080

2. Visit http://127.0.0.1:8080 to view the application.

If you need to add or update dependencies, follow the guidance in Working on projects | uv

Pre-commit¶

This project uses pre-commit to manage pre-commit hooks. To install the pre-commit hooks, run:

pre-commit install

This will set up the hooks defined in .pre-commit-config.yaml to run automatically on git commit.

Chartpress¶

Helm charts are automatically published with Chartpress and hosted at 2i2c.org/jupyterhub-cost-monitoring.

Images are hosted at Quay.io.

See the configuration in the chartpress.yaml file for more details.

Running tests¶

To run tests, use pytest:

uv run pytest

Documentation¶

The documentation is built using MySTMD and hosted at jupyterhub-cost-monitoring.readthedocs.io.

To build the documentation locally, run:

cd docs
uv run myst start

To build the API documentation, download the OpenAPI specification from the FastAPI server default URL /openapi.json and place it in the docs/reference directory.

Install widdershins to convert this to a Markdown and name this docs/reference/api.md:

npm install -g widdershins
widdershins --code --summary true --user_templates api_templates openapi.json -o api.md

There are custom templates in docs/reference/api_templates to style the output.