Polish Great Docs onboarding and API conventions

README.md

@@ -10,9 +10,17 @@
 
 The library is designed to be easy to use while still offering a high degree of control over the final plots.
 
+For some reproducible examples please visit [rtichoke blog](https://rtichoke-blog.netlify.app/)!
+
 ## Installation
 
-Install `rtichoke` from PyPI:
+For a project managed with [uv](https://docs.astral.sh/uv/), add `rtichoke` with:
+
+```bash
+uv add rtichoke
+```
+
+Alternatively, install `rtichoke` from PyPI with pip:
 
 ```bash
 pip install rtichoke

great-docs.yml

@@ -1,49 +1,73 @@
-display_name: rtichoke
-parser: numpy
-repo: https://github.com/uriahf/rtichoke_python
-user_guide: user_guide
-homepage: user_guide
+display_name: rtichoke
+parser: numpy
+repo: https://github.com/uriahf/rtichoke_python
+user_guide: user_guide
+homepage: user_guide
 site_url: https://uriahf.github.io/rtichoke_python/
 
+include_in_header:
+  - text: |
+      <script>
+      document.addEventListener('DOMContentLoaded', () => {
+        const nav = document.querySelector('nav.navbar ul.navbar-nav.me-auto');
+        if (!nav || nav.querySelector('[data-rtichoke-blog-link]')) return;
+
+        const item = document.createElement('li');
+        item.className = 'nav-item';
+        item.setAttribute('data-rtichoke-blog-link', '');
+
+        const link = document.createElement('a');
+        link.className = 'nav-link';
+        link.href = 'https://rtichoke-blog.netlify.app/';
+        link.textContent = 'Blog ↗';
+
+        item.appendChild(link);
+        const reference = [...nav.children].find((el) =>
+          el.textContent.trim().toLowerCase().includes('reference')
+        );
+        nav.insertBefore(item, reference || null);
+      });
+      </script>
+
 site:
   css: site.css
 
 source:
-  enabled: true
-  branch: main
-  placement: usage
-
-reference:
-  - title: Performance Data
-    desc: Prepare classification and time-to-event data for visualization.
-    contents:
-      - prepare_performance_data
-      - prepare_binned_classification_data
-      - prepare_performance_data_times
-      - prepare_binned_classification_data_times
-
-  - title: Discrimination
-    desc: ROC, precision-recall, gains, and lift visualizations.
-    contents:
-      - create_roc_curve
-      - create_roc_curve_times
-      - plot_roc_curve
-      - create_precision_recall_curve
-      - create_precision_recall_curve_times
-      - plot_precision_recall_curve
-      - create_gains_curve
-      - create_gains_curve_times
-      - plot_gains_curve
-      - create_lift_curve
-      - create_lift_curve_times
-      - plot_lift_curve
-
-  - title: Calibration
-    desc: Calibration visualizations for classification and time-to-event models.
-    contents:
-      - create_calibration_curve
-      - create_calibration_curve_times
-
+  enabled: true
+  branch: main
+  placement: usage
+
+reference:
+  - title: Performance Data
+    desc: Prepare classification and time-to-event data for visualization.
+    contents:
+      - prepare_performance_data
+      - prepare_binned_classification_data
+      - prepare_performance_data_times
+      - prepare_binned_classification_data_times
+
+  - title: Discrimination
+    desc: ROC, precision-recall, gains, and lift visualizations.
+    contents:
+      - create_roc_curve
+      - create_roc_curve_times
+      - plot_roc_curve
+      - create_precision_recall_curve
+      - create_precision_recall_curve_times
+      - plot_precision_recall_curve
+      - create_gains_curve
+      - create_gains_curve_times
+      - plot_gains_curve
+      - create_lift_curve
+      - create_lift_curve_times
+      - plot_lift_curve
+
+  - title: Calibration
+    desc: Calibration visualizations for classification and time-to-event models.
+    contents:
+      - create_calibration_curve
+      - create_calibration_curve_times
+
   - title: Utility
     desc: Decision-curve analysis for classification and time-to-event models.
     contents:

user_guide/00-getting-started.qmd

@@ -5,9 +5,19 @@ guide-section: "Getting Started"
 
 `rtichoke` is a Python library for interactive visualization of predictive-model performance. It supports discrimination, calibration, utility, and time-to-event evaluation workflows.
 
+For some reproducible examples please visit [rtichoke blog](https://rtichoke-blog.netlify.app/)!
+
 ## Installation
 
-Install `rtichoke` from PyPI:
+If you use [uv](https://docs.astral.sh/uv/) to manage your Python project, add `rtichoke` with:
+
+```bash
+uv add rtichoke
+```
+
+This adds `rtichoke` to your project dependencies and updates the uv lockfile.
+
+If you are not using uv, install `rtichoke` from PyPI with pip:
 
 ```bash
 pip install rtichoke
@@ -89,4 +99,4 @@ fig = rk.create_calibration_curve(
 fig.show()
 ```
 
-From here, use the API Reference for the full set of curve types, parameters, and time-to-event variants.
+From here, use the API Reference for the full set of curve types, parameters, and time-to-event variants. The [Naming Conventions](user-guide/naming-conventions.html) guide explains how the exported function families fit together.

user_guide/01-naming-conventions.qmd

@@ -0,0 +1,56 @@
+---
+title: "Naming Conventions"
+guide-section: "Getting Started"
+---
+
+`rtichoke` uses consistent function names so that the API becomes easier to predict once you know the main families.
+
+## Function families
+
+| Prefix | Purpose | Typical input | Typical output |
+|---|---|---|---|
+| `prepare_*` | Prepare reusable performance data | predictions and observed outcomes | performance data |
+| `create_*` | Prepare data and create a visualization in one call | predictions and observed outcomes | interactive figure |
+| `plot_*` | Visualize data that has already been prepared | performance data | interactive figure |
+
+For example, a direct ROC workflow uses `create_roc_curve()`, while a workflow that first prepares reusable performance data can pass those results to `plot_roc_curve()`.
+
+## Curve families
+
+The same naming pattern repeats across the main performance views:
+
+| Performance view | Direct visualization | Plot prepared data |
+|---|---|---|
+| ROC | `create_roc_curve()` | `plot_roc_curve()` |
+| Precision–Recall | `create_precision_recall_curve()` | `plot_precision_recall_curve()` |
+| Gains | `create_gains_curve()` | `plot_gains_curve()` |
+| Lift | `create_lift_curve()` | `plot_lift_curve()` |
+| Decision curve | `create_decision_curve()` | `plot_decision_curve()` |
+
+Calibration currently uses the direct `create_calibration_curve()` interface.
+
+## Time-to-event variants
+
+Functions ending in `_times` extend the corresponding workflow to time-to-event outcomes. For example:
+
+- `create_roc_curve()` → binary-outcome ROC curve
+- `create_roc_curve_times()` → time-to-event ROC curve
+- `create_calibration_curve()` → binary-outcome calibration curve
+- `create_calibration_curve_times()` → time-to-event calibration curve
+- `create_decision_curve()` → binary-outcome decision curve
+- `create_decision_curve_times()` → time-to-event decision curve
+
+The same convention is used for the performance-data preparation functions, such as `prepare_performance_data()` and `prepare_performance_data_times()`.
+
+## A useful mental model
+
+Think of the API as a small grammar:
+
+```text
+prepare + performance data        -> reusable data
+create  + metric/curve            -> data to figure
+plot    + metric/curve            -> prepared data to figure
+*_times                           -> time-to-event version
+```
+
+This convention is intended to make related functions discoverable without requiring users to memorize every exported name.