From b7827a534521b88fed4ae5b376120afce1b96f65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Faria?= <joao.faria@unige.ch>
Date: Tue, 9 Jul 2024 18:17:34 +0200
Subject: [PATCH] update pykima API

---
 docs/docs/API/pykima.md | 78 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 72 insertions(+), 6 deletions(-)

diff --git a/docs/docs/API/pykima.md b/docs/docs/API/pykima.md
index 8a661d0..5ba9e3b 100644
--- a/docs/docs/API/pykima.md
+++ b/docs/docs/API/pykima.md
@@ -1,13 +1,79 @@
 # API documentation for `pykima`
 
-**kima** itself is written in C++, to leverage the increased performance. 
-The Python bindings created with [nanobind](https://github.com/wjakob/nanobind)
-expose most of the functionality of the data ([RVData][kima.RVData]) 
-and model classes (e.g. [RVmodel][kima.RVmodel], [GPmodel][kima.GPmodel], etc.),
-as well as the sampler ([kima.run][kima.run]).
+**kima** itself is written in C++, to leverage the increased performance. The
+Python bindings created with [nanobind](https://github.com/wjakob/nanobind)
+expose most of the functionality of the data ([RVData][kima.Data.RVData]) and
+model classes (e.g. [RVmodel][kima.RVmodel], [GPmodel][kima.GPmodel], etc.), as
+well as the sampler ([kima.run][kima.Sampler.run]).
 
 To analyse the results and create figures, the `pykima` sub-package was created.
-It can be used in an IPython shell, a Jupyter notebook, or the standard Python interpreter.
+It can be used in an IPython shell, a Jupyter notebook, or the standard Python
+interpreter.
 
 ---
 
+The typical interface with the results of a run is through the
+[`KimaResults`][pykima.results.KimaResults] class created by calling the
+[`kima.load_results`][pykima.results.load_results] function
+
+```python
+model ...
+res = kima.load_results(model)
+```
+
+
+??? example "`KimaResults` class"
+
+    ::: pykima.results.KimaResults
+        handler: python
+        options:
+          show_source: false
+          heading_level: 6
+          filters:
+            - "!^_"
+            - "!ESS"
+
+??? example "`kima.load_results` API"
+
+    ::: pykima.results.load_results
+        handler: python
+        options:
+          show_source: false
+          heading_level: 6
+          filters:
+            - "!^_"
+
+
+A number of convenience plots are redirected from the
+[`pykima.display`][pykima.display] module into any
+[`KimaResults`][pykima.results.KimaResults] instance:
+
+
+```python
+res.plot_posterior_np()
+
+res.plot_posterior_period()
+```
+
+!!! note
+
+    Several of the plotting functions are aliased and numbered, as in
+
+    ```py
+    res.plot1 = res.plot_posterior_np
+    ```
+
+    This can be convenient, but it's mostly for historical reasons and 
+    the API might change at any time. Therefore, these funcions are not
+    documented.
+
+
+??? example "`load_results` class"
+
+    ::: pykima.display
+        handler: python
+        options:
+          show_source: false
+          heading_level: 6
+          filters:
+            - "!^_"
\ No newline at end of file