From 978f12c6392449811f04d35d9a86ec7b7f874adc Mon Sep 17 00:00:00 2001
From: zombie-einstein <13398815+zombie-einstein@users.noreply.github.com>
Date: Thu, 28 Mar 2024 00:27:08 +0000
Subject: [PATCH] Restructure toctrees and some formatting fixes (#19)

---
 docs/source/conf.py                           |  8 ++++--
 docs/source/index.rst                         | 15 ++++++----
 docs/source/pages/api.rst                     | 28 +++++++++++--------
 .../pages/numpy_discrete_event_usage.rst      |  4 +--
 docs/source/pages/usage.rst                   | 23 +++++++++------
 pyproject.toml                                |  2 +-
 6 files changed, 51 insertions(+), 29 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 4d9cf02..03ef996 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -44,12 +44,16 @@
 
 html_theme_options = {
     "repo_url": "https://github.com/zombie-einstein/bourse",
-    "icon": {"repo": "fontawesome/brands/github", "logo": "material/chart-line"},
+    "icon": {
+        "repo": "fontawesome/brands/github",
+        "logo": "material/chart-line",
+    },
     "palette": {
         "scheme": "slate",
         "primary": "black",
     },
-    "toc_title_is_page_title": True,
+    "toc_title": "Contents",
+    # "toc_title_is_page_title": True,
 }
 
 python_apigen_order_tiebreaker = "alphabetical"
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 0729c14..4e4b44d 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -2,14 +2,19 @@
 Bourse
 *******
 
-A Rust market simulator with
-Python interface designed for high
-performance agent based models and
-reinforcement learning.
+A Rust limit order-book and market simulator with
+a Python interface. Designed for high performance
+agent based models and reinforcement learning.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents
+   :hidden:
+
+   Index<self>
+
+.. toctree::
+   :maxdepth: 2
+   :includehidden:
 
    pages/getting_started
    pages/usage
diff --git a/docs/source/pages/api.rst b/docs/source/pages/api.rst
index f1a094b..98372c4 100644
--- a/docs/source/pages/api.rst
+++ b/docs/source/pages/api.rst
@@ -2,22 +2,28 @@
 API Reference
 *************
 
-.. python-apigen-group:: data_processing
-
-.. python-apigen-group:: step_sim
+Order Book
+==========
 
-.. python-apigen-group:: base_agent_class
+.. python-apigen-group:: order_book_class
+.. python-apigen-group:: public-members
 
-.. python-apigen-group:: base_numpy_agent_class
+Discrete Event Simulation
+=========================
 
+.. python-apigen-group:: step_sim
+.. python-apigen-group:: step_env_class
+.. python-apigen-group:: base_agent_class
 .. python-apigen-group:: random_agent_class
 
-.. python-apigen-group:: n_random_agent_class
-
-.. python-apigen-group:: order_book_class
-
-.. python-apigen-group:: step_env_class
+Discrete Event Numpy API
+========================
 
 .. python-apigen-group:: step_env_numpy_class
+.. python-apigen-group:: base_numpy_agent_class
+.. python-apigen-group:: n_random_agent_class
 
-.. python-apigen-group:: public-members
+Utils
+=====
+
+.. python-apigen-group:: data_processing
diff --git a/docs/source/pages/numpy_discrete_event_usage.rst b/docs/source/pages/numpy_discrete_event_usage.rst
index eaac180..4b3f71b 100644
--- a/docs/source/pages/numpy_discrete_event_usage.rst
+++ b/docs/source/pages/numpy_discrete_event_usage.rst
@@ -1,5 +1,5 @@
-Numpy Discrete Event Simulation Environment
--------------------------------------------
+Numpy Discrete Event Environment
+--------------------------------
 
 This environment allows market state and market instructions
 to be returned/submitted as Numpy arrays. This has the
diff --git a/docs/source/pages/usage.rst b/docs/source/pages/usage.rst
index 56c643b..5606ce6 100644
--- a/docs/source/pages/usage.rst
+++ b/docs/source/pages/usage.rst
@@ -5,18 +5,25 @@ Bourse allows Python users/programs to interact
 with three core pieces of functionality
 from the Rust package:
 
-- An orderbook that allow orders to be directly
-  placed and modified.
-- A discrete event simulation environment that
+- :doc:`order_book_usage`
+
+  An orderbook that allow orders to be directly
+  placed and modified, and tracks trade and order data.
+
+- :doc:`discrete_event_usage`
+
+  A discrete event simulation environment that
   allows Python agents to submit trade
-  instructions with functionality to update
+  instructions, with functionality to update
   simulation state and track simulation data.
-- A discrete event simulation environment can receive
-  instructions and returns data in the format of
-  Numpy arrays.
+
+- :doc:`numpy_discrete_event_usage`
+
+  A discrete event simulation environment can receive
+  instructions and returns data as Numpy arrays.
 
 .. toctree::
-   :maxdepth: 2
+   :hidden:
 
    order_book_usage
    discrete_event_usage
diff --git a/pyproject.toml b/pyproject.toml
index 9c0a715..38d3160 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -71,7 +71,7 @@ dependencies = [
   "maturin >= 1.2.3",
   "patchelf >= 0.17.2.1; platform_system != 'Darwin'",
   "sphinx >= 7.2.6",
-  "sphinx-immaterial >= 0.11.10",
+  "sphinx-immaterial >= 0.11.11",
 ]
 
 [tool.hatch.envs.docs.scripts]