From 5d8ea2192a9e51604795b4db5895c0b4c795087a Mon Sep 17 00:00:00 2001
From: Roland Conybeare <rconybeare@gmail.com>
Date: Thu, 9 May 2024 08:45:51 -0400
Subject: [PATCH] xo-unit: + bpu-class docs

---
 docs/CMakeLists.txt     |  2 +-
 docs/bpu-class.rst      | 32 ++++++++++++++++++++++++++++++++
 docs/implementation.rst | 10 +++++-----
 docs/index.rst          |  1 +
 4 files changed, 39 insertions(+), 6 deletions(-)
 create mode 100644 docs/bpu-class.rst

diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 2fe3b9af..f221b09c 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -5,7 +5,7 @@ xo_docdir_doxygen_config()
 xo_docdir_sphinx_config(
     index.rst examples.rst glossary.rst install.rst implementation.rst development.rst
     quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst
-    unit-reference.rst unit-concept.rst unit-quantities.rst bu-store-class.rst basis-unit-reference.rst
+    unit-reference.rst unit-concept.rst unit-quantities.rst bpu-class.rst bu-store-class.rst basis-unit-reference.rst
     basis-unit-class.rst basis-unit-constants.rst
     dimension-enum.rst
 )
diff --git a/docs/bpu-class.rst b/docs/bpu-class.rst
new file mode 100644
index 00000000..e8c90a00
--- /dev/null
+++ b/docs/bpu-class.rst
@@ -0,0 +1,32 @@
+.. _bpu-class:
+
+BPU
+===
+
+.. code-block:: cpp
+
+    #include <xo/unit/bpu.hpp>
+
+A :code:`xo::qty::bpu` represents a rational (usually integer) power of a :doc:`basis-unit-class`.
+
+For example:
+
+.. uml::
+    :caption: representation for cubic millimeters
+    :scale: 99%
+    :align: center
+
+    object mm3<<bpu>>
+    mm3 : native_dim = dim::distance
+    mm3 : scalefactor = 1/1000
+    mm3 : power = 3/1
+
+.. uml::
+    :caption: representation for annual (365-day) volatility
+    :scale: 99%
+    :align: center
+
+    object vol<<bpu>>
+    vol : native_dim = dim::time
+    vol : scalefactor = 365*24*3600
+    vol : power = -1/2
diff --git a/docs/implementation.rst b/docs/implementation.rst
index e95d96d0..2b89fb48 100644
--- a/docs/implementation.rst
+++ b/docs/implementation.rst
@@ -48,21 +48,21 @@ Abstraction tower for *xo-unit* components.
   - natural_units are *not* closed under multiplication and division.
     (for example consider :code:`xo::qty::qty::foot * xo::qty::qty::meter`)
 
-- bpu:
+- bpu: :doc:`bpu-class`.
 
-  A power of a basis unit. Has a single dimension.
+  A rational (usually integer) power of a basis unit. Has a single dimension.
 
-- bu_store: see :doc:`bu-store-class`.
+- bu_store: :doc:`bu-store-class`.
 
   Associates basis units with abbreviations.
 
   For example ``bu::kilogram`` => ``"kg"``
 
-- basis_unit: see :doc:`basis-unit-reference`.
+- basis_unit: :doc:`basis-unit-reference`.
 
   A unit with a single dimension and scale.
 
-- dimension: see :doc:`dimension-enum`.
+- dimension: :doc:`dimension-enum`.
 
   identifies a dimension, such as mass or time.
 
diff --git a/docs/index.rst b/docs/index.rst
index 2b0a2153..f0584e79 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,6 +37,7 @@ runtime (since we can't construct new c++ types at runtime).
    unit-quantities
    quantity-reference
    unit-reference
+   bpu-class
    bu-store-class
    basis-unit-reference
    dimension-enum