From c419c390a53fcf238a9185ae1e768c0f57471ff0 Mon Sep 17 00:00:00 2001
From: Matthew Evans <7916000+ml-evs@users.noreply.github.com>
Date: Wed, 13 Sep 2023 14:54:36 +0200
Subject: [PATCH] Manual overhaul of API docs (#451)

---
 README.md                           | 2 +-
 mkdocs.yml                          | 3 +++
 pydatalab/docs/.pages               | 6 ++++--
 pydatalab/docs/api_reference.md     | 1 -
 pydatalab/docs/api_reference/.pages | 1 -
 pydatalab/docs/blocks/.pages        | 1 +
 pydatalab/docs/blocks/apps/.pages   | 1 +
 pydatalab/docs/blocks/apps/chat.md  | 2 ++
 pydatalab/docs/blocks/apps/echem.md | 2 ++
 pydatalab/docs/blocks/apps/eis.md   | 2 ++
 pydatalab/docs/blocks/apps/nmr.md   | 2 ++
 pydatalab/docs/blocks/apps/raman.md | 1 +
 pydatalab/docs/blocks/apps/tga.md   | 2 ++
 pydatalab/docs/blocks/apps/xrd.md   | 2 ++
 pydatalab/docs/blocks/base.md       | 1 +
 pydatalab/docs/blocks/common.md     | 1 +
 pydatalab/docs/config.md            | 2 ++
 pydatalab/docs/css/reference.css    | 3 +++
 pydatalab/docs/rest_api.md          | 3 +++
 pydatalab/docs/schemas/.pages       | 2 +-
 20 files changed, 34 insertions(+), 6 deletions(-)
 delete mode 100644 pydatalab/docs/api_reference.md
 delete mode 100644 pydatalab/docs/api_reference/.pages
 create mode 100644 pydatalab/docs/blocks/.pages
 create mode 100644 pydatalab/docs/blocks/apps/.pages
 create mode 100644 pydatalab/docs/blocks/apps/chat.md
 create mode 100644 pydatalab/docs/blocks/apps/echem.md
 create mode 100644 pydatalab/docs/blocks/apps/eis.md
 create mode 100644 pydatalab/docs/blocks/apps/nmr.md
 create mode 100644 pydatalab/docs/blocks/apps/raman.md
 create mode 100644 pydatalab/docs/blocks/apps/tga.md
 create mode 100644 pydatalab/docs/blocks/apps/xrd.md
 create mode 100644 pydatalab/docs/blocks/base.md
 create mode 100644 pydatalab/docs/blocks/common.md
 create mode 100644 pydatalab/docs/config.md
 create mode 100644 pydatalab/docs/css/reference.css
 create mode 100644 pydatalab/docs/rest_api.md

diff --git a/README.md b/README.md
index 23fe45076..33fe36423 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@ in the Department of Chemistry at the University of Cambridge.
 - A simple, intuitive UI for recording sample metadata and relationships with
   other samples (batches, offshoots), alongside synthesis parameters and raw data.
 - Basic analysis and plotting of live and archived data attached to a sample, e.g.,
-  characterisation via XRD or NMR, electrochemical cycling data and images -- see Blocks for a complete list.
+  characterisation via XRD or NMR, electrochemical cycling data and images (see "Data blocks" section for a complete list).
 - Interactive network visualisation of the connections between samples and inventory.
 
 ## Development status
diff --git a/mkdocs.yml b/mkdocs.yml
index 2e79ad9dc..a49a457c6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -41,6 +41,9 @@ markdown_extensions:
   - toc:
       permalink: true
 
+extra_css:
+  - css/reference.css
+
 plugins:
   - mkdocstrings:
       default_handler: python
diff --git a/pydatalab/docs/.pages b/pydatalab/docs/.pages
index d8ba635ad..dab24a68c 100644
--- a/pydatalab/docs/.pages
+++ b/pydatalab/docs/.pages
@@ -2,5 +2,7 @@ nav:
     - index.md
     - INSTALL.md
     - design
-    - 'Model schemas': schemas
-    - api_reference.md
+    - schemas
+    - blocks
+    - rest_api.md
+    - config.md
diff --git a/pydatalab/docs/api_reference.md b/pydatalab/docs/api_reference.md
deleted file mode 100644
index 81423131b..000000000
--- a/pydatalab/docs/api_reference.md
+++ /dev/null
@@ -1 +0,0 @@
-::: pydatalab
diff --git a/pydatalab/docs/api_reference/.pages b/pydatalab/docs/api_reference/.pages
deleted file mode 100644
index 9385270ba..000000000
--- a/pydatalab/docs/api_reference/.pages
+++ /dev/null
@@ -1 +0,0 @@
-title: "API Reference"
diff --git a/pydatalab/docs/blocks/.pages b/pydatalab/docs/blocks/.pages
new file mode 100644
index 000000000..b7af13736
--- /dev/null
+++ b/pydatalab/docs/blocks/.pages
@@ -0,0 +1 @@
+title: Data blocks
diff --git a/pydatalab/docs/blocks/apps/.pages b/pydatalab/docs/blocks/apps/.pages
new file mode 100644
index 000000000..7c3cc04c6
--- /dev/null
+++ b/pydatalab/docs/blocks/apps/.pages
@@ -0,0 +1 @@
+title: Applications
diff --git a/pydatalab/docs/blocks/apps/chat.md b/pydatalab/docs/blocks/apps/chat.md
new file mode 100644
index 000000000..cd6cfa407
--- /dev/null
+++ b/pydatalab/docs/blocks/apps/chat.md
@@ -0,0 +1,2 @@
+title: Whinchat (LLM assistant)
+::: pydatalab.apps.chat
diff --git a/pydatalab/docs/blocks/apps/echem.md b/pydatalab/docs/blocks/apps/echem.md
new file mode 100644
index 000000000..9b2578c95
--- /dev/null
+++ b/pydatalab/docs/blocks/apps/echem.md
@@ -0,0 +1,2 @@
+title: Electrochemistry
+::: pydatalab.apps.echem
diff --git a/pydatalab/docs/blocks/apps/eis.md b/pydatalab/docs/blocks/apps/eis.md
new file mode 100644
index 000000000..ca33f752b
--- /dev/null
+++ b/pydatalab/docs/blocks/apps/eis.md
@@ -0,0 +1,2 @@
+title: EIS
+::: pydatalab.apps.eis
diff --git a/pydatalab/docs/blocks/apps/nmr.md b/pydatalab/docs/blocks/apps/nmr.md
new file mode 100644
index 000000000..208572fec
--- /dev/null
+++ b/pydatalab/docs/blocks/apps/nmr.md
@@ -0,0 +1,2 @@
+title: NMR
+::: pydatalab.apps.nmr
diff --git a/pydatalab/docs/blocks/apps/raman.md b/pydatalab/docs/blocks/apps/raman.md
new file mode 100644
index 000000000..8988e0564
--- /dev/null
+++ b/pydatalab/docs/blocks/apps/raman.md
@@ -0,0 +1 @@
+::: pydatalab.apps.raman
diff --git a/pydatalab/docs/blocks/apps/tga.md b/pydatalab/docs/blocks/apps/tga.md
new file mode 100644
index 000000000..be68c5358
--- /dev/null
+++ b/pydatalab/docs/blocks/apps/tga.md
@@ -0,0 +1,2 @@
+title: TGA
+::: pydatalab.apps.tga
diff --git a/pydatalab/docs/blocks/apps/xrd.md b/pydatalab/docs/blocks/apps/xrd.md
new file mode 100644
index 000000000..790aa8f35
--- /dev/null
+++ b/pydatalab/docs/blocks/apps/xrd.md
@@ -0,0 +1,2 @@
+title: XRD
+::: pydatalab.apps.xrd
diff --git a/pydatalab/docs/blocks/base.md b/pydatalab/docs/blocks/base.md
new file mode 100644
index 000000000..f2378578c
--- /dev/null
+++ b/pydatalab/docs/blocks/base.md
@@ -0,0 +1 @@
+::: pydatalab.blocks.base
diff --git a/pydatalab/docs/blocks/common.md b/pydatalab/docs/blocks/common.md
new file mode 100644
index 000000000..8da5b32d4
--- /dev/null
+++ b/pydatalab/docs/blocks/common.md
@@ -0,0 +1 @@
+::: pydatalab.blocks.common
diff --git a/pydatalab/docs/config.md b/pydatalab/docs/config.md
new file mode 100644
index 000000000..7484317bc
--- /dev/null
+++ b/pydatalab/docs/config.md
@@ -0,0 +1,2 @@
+title: Server configuration
+::: pydatalab.config
diff --git a/pydatalab/docs/css/reference.css b/pydatalab/docs/css/reference.css
new file mode 100644
index 000000000..6ba282104
--- /dev/null
+++ b/pydatalab/docs/css/reference.css
@@ -0,0 +1,3 @@
+.md-grid {
+    max-width: 70rem;
+}
diff --git a/pydatalab/docs/rest_api.md b/pydatalab/docs/rest_api.md
new file mode 100644
index 000000000..5c5251545
--- /dev/null
+++ b/pydatalab/docs/rest_api.md
@@ -0,0 +1,3 @@
+# REST API
+
+::: pydatalab.routes.v0_1
diff --git a/pydatalab/docs/schemas/.pages b/pydatalab/docs/schemas/.pages
index c80923a47..5da590f09 100644
--- a/pydatalab/docs/schemas/.pages
+++ b/pydatalab/docs/schemas/.pages
@@ -1 +1 @@
-title: "Schemas"
+title: "Data models"