docs: add group costs and api reference (#98)

* Add toc

* docs: update group costs

* docs: add API reference

* Update symlinks

Author: jnywong

CODE-OF-CONDUCT.md

@@ -1 +1,3 @@
-Please refer to [Project Jupyter's Code of Conduct](https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md).
+# Code of Conduct
+
+This project abides by [Project Jupyter's Code of Conduct](https://github.com/jupyter/governance/blob/HEAD/conduct/code_of_conduct.md).

CONTRIBUTING.md

@@ -34,11 +34,11 @@ This project uses the Python package manager `uv`. Below are the steps to set up
   aws sts get-session-token --serial-number $MFA_DEVICE_ID --profile $AWS_PROFILE --token-code ******
   ```
 
-1. Run the Flask web server
+1. Run the FastAPI web server
 
    ```bash
    cd src/jupyterhub_cost_monitoring
-   flask run --port=8080 --reload
+   fastapi dev app.py --port 8080
    ```
 
 1. Visit [http://127.0.0.1:8080](http://127.0.0.1:8080) to view the application.
@@ -70,3 +70,25 @@ To run tests, use `pytest`:
 ```bash
 uv run pytest
 ```
+
+## Documentation
+
+The documentation is built using [MySTMD](https://mystmd.org/) and hosted at [jupyterhub-cost-monitoring.readthedocs.io](https://jupyterhub-cost-monitoring.readthedocs.io/).
+
+To build the documentation locally, run:
+
+```bash
+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`](https://github.com/Mermade/widdershins) to convert this to a Markdown and name this `docs/reference/api.md`:
+
+```bash
+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.

LICENSE LICENSE.mdLICENSE renamed to LICENSE.md

@@ -1,3 +1,5 @@
+# License
+
 BSD 3-Clause License
 
 Copyright (c) 2025, 2i2c
@@ -25,4 +27,4 @@ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,6 +1,6 @@
 # jupyterhub-cost-monitoring
 
-![Grafana dashboard with multiple panels showing stacked bar charts of user cloud costs over time.](./images/dashboard.png)
+![Grafana dashboard with multiple panels showing stacked bar charts of user cloud costs over time.](./images/dashboard_users.png)
 
 Cloud cost monitoring is moving beyond just preventing runaway cost explosions – it’s about empowering JupyterHub administrators with the guardrails they need to run efficient, transparent, and sustainable infrastructures. A cloud cost bill can show a broad view of services and machines provisioned, but how can we provide granular insights into each user and the value they are deriving from the hub on an application level?  
 
@@ -14,7 +14,7 @@ This tool provides a per-user cost reporting system for JupyterHubs running on A
 
 ## Installation
 
-[Helm Chart Repository](https://2i2c.org/jupyterhub-cost-monitoring/)
+📦 Packaged helm charts for this project can be found at [https://2i2c.org/jupyterhub-cost-monitoring/](https://2i2c.org/jupyterhub-cost-monitoring/).
 
 This project is designed to be compatible with Zero to JupyterHub distributions, making it easy to deploy in the cloud with Kubernetes.
 
@@ -38,9 +38,11 @@ jupyterhub-cost-monitoring:
       value: "<name-of-cluster>"
 ```
 
+An example of configuring an AWS IAM role to talk to the AWS Cost Explorer API can be found in the [2i2c Infrastructure Guide](https://infrastructure.2i2c.org/topic/billing/cost-monitoring-system/).
+
 ## Documentation
 
-Please refer to the documentation at [https://jupyterhub-cost-monitoring.readthedocs.io/en/latest/](https://jupyterhub-cost-monitoring.readthedocs.io/en/latest/)
+Documentation can be found at [https://jupyterhub-cost-monitoring.readthedocs.io/en/latest/](https://jupyterhub-cost-monitoring.readthedocs.io/en/latest/)
 
 ## Contributing
 
@@ -54,4 +56,10 @@ Please refer to [`CONTRIBUTING.md`](CONTRIBUTING.md) for more details.
 
 ## License
 
-This project is licensed under the [BSD 3-Clause License](LICENSE).
+This project is licensed under the [BSD 3-Clause License](LICENSE.md).
+
+## Resources
+
+- [Documentation](https://jupyterhub-cost-monitoring.readthedocs.io/en/latest/)
+- [2i2c Infrastructure Guide](https://infrastructure.2i2c.org/topic/billing/cost-monitoring-system/)
+- [Helm Chart Repository](https://2i2c.org/jupyterhub-cost-monitoring/)

docs/CONTRIBUTING.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

docs/CONTRIBUTING.md

@@ -1,29 +1,43 @@
-# Explore the Dashboard
+# Explore the Dashboards
 
-![Grafana dashboard with multiple panels showing stacked bar charts of user cloud costs over time.](../images/dashboard.png)
+## User cloud costs
 
-## Navigate to the *Cloud costs per user* dashboard
+![Grafana dashboard with multiple panels showing stacked bar charts of user cloud costs over time.](../images/dashboard_users.png)
+
+### Navigate to the *Cloud costs per user* dashboard
 
 From the Grafana homepage, navigate to *Home > Dashboards > Cloud cost dashboards* and then click on *Cloud costs per user*.
 
 This will load the dashboard, which may take a few moments to populate with data.
 
-## Understand the dashboard layout
+### Understand the user costs dashboard layout
 
 The dashboard is organized into several panels, each providing insights into different aspects of user cloud costs:
 
 - **Top 5 Users**: a quick at a glance view of the top 5 users by total cost over the selected time range.
 - **Total by Hub**: a breakdown of total costs by hub, allowing you to see which hubs are incurring the most expenses.
 - **Total by Component**: a breakdown of total costs by [component](../topics/components.md), helping you identify which resources are driving costs.
-- **Hub**: individual panels for each hub, showing daily costs by users within that hub. User costs summed over all hubs is shown by default. Try toggling the variable `hub` at the top of the dashboard to see splits by individual hubs.
-- **Component**: individual panels showing daily costs by users for compute and home storage. You can also toggle the variable `component` at the top of the dashboard to show or hide panels.
+- **Hub – Component**: daily user costs. Sums over all hubs and components are shown by default. Try toggling the variable `hub` and `component` at the top of the dashboard to filter between hubs, or home storage and compute components.
+
+## Group cloud costs
+
+![Grafana dashboard with multiple panels showing time series charts of group cloud costs over time.](../images/dashboard_groups.png)
+
+### Understand the group costs dashboard layout
+
+The Group Costs dashboard is organized into the following panels:
+
+- **Total by Group**: a breakdown of total costs by user group, summed over the selected time range.
+- **Users with multiple group memberships**: a table of users who belong to more than one group, where their costs are double-counted in group costs.
+- **Users with no group memberships**: a table of users who do not belong to any group, where their costs are not attributed to any group.
+- **Hub – Component**: daily group costs. Sums over all hubs and components are shown by default. Try toggling the variable `hub` and `component` at the top of the dashboard to filter between hubs, or home storage and compute components.
 
 ## Interact with the dashboard
 
-You can interact with the dashboard in several ways:
+You can interact with the dashboards in several ways:
 
 - **Time Range**: use the time range selector in the top right corner to adjust the period for which data is displayed. The last 30 days are shown by default. The timezone is always UTC, since daily cost data prepared by cloud providers is typically settled at 00:00 UTC.
-- **Variables**: use the dropdowns at the top of the dashboard to filter data by hub or component.
+- **Variables**: use the dropdowns at the top of the dashboard to filter data by hub, component or group, or limit number of users displayed.
 - **Legend**: click on user names in the legend to isolate or hide specific users in the graphs. You can select multiple users by holding down the `Shift` key while clicking, and double-click to reset the selection.
 - **Tooltips**: hover over data points in the graphs to see detailed information, including exact cost values and timestamps of each user.
 

docs/how-to/dashboard.md

@@ -8,6 +8,24 @@ project:
   # authors: []
   github: https://github.com/2i2c-org/jupyterhub-cost-monitoring
   # To autogenerate a Table of Contents, run "myst init --write-toc"
+  toc:
+    # Auto-generated by `myst init --write-toc`
+  - file: README.md
+  - title: How To
+    children:
+    - file: how-to/dashboard.md
+  - title: Topics
+    children:
+    - file: topics/architecture.md
+    - file: topics/components.md
+    - file: topics/cost-calculations.md
+  - title: Reference
+    children:
+    - file: reference/api.md
+    - file: reference/License.md
+    - file: reference/CODE-OF-CONDUCT.md
+  - file: CONTRIBUTING.md
+
 site:
   template: book-theme
   # options:

docs/myst.yml

@@ -0,0 +1 @@
+../../CODE-OF-CONDUCT.md

docs/reference/CODE-OF-CONDUCT.md

@@ -0,0 +1 @@
+../../LICENSE.md