xo-unit ++ docs ++ quantity arithmetic + example

Rconybea · May 23, 2024 · b0ce5ea · b0ce5ea
1 parent 412a0ba
commit b0ce5ea
Show file tree

Hide file tree

Showing 34 changed files with 713 additions and 173 deletions.
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -3,14 +3,16 @@
 xo_doxygen_collect_deps()
 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
+    index.rst examples.rst glossary.rst install.rst implementation.rst
+    quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst quantity-source-code.rst
     xquantity-reference.rst xquantity-class.rst
     scaled-unit-reference.rst scaled-unit-class.rst scaled-unit-constants.rst
     natural-unit-class.rst
     bpu-class.rst
     bu-store-class.rst basis-unit-reference.rst
     basis-unit-class.rst basis-unit-constants.rst
     dimension-enum.rst
+    development.rst
+    ubuntu-github-workflow.rst
 )
 #xo_utest_coverage_config2()
diff --git a/docs/basis-unit-class.rst b/docs/basis-unit-class.rst
@@ -22,7 +22,7 @@ Context
     +----------------+               |
     |    bu_store    |               |
     +----------------+---------------+
-    |cYEL       basis_unit           |
+    |cBLU       basis_unit           |
     +--------------------------------+
     |            dimension           |
     +--------------------------------+

diff --git a/docs/basis-unit-constants.rst b/docs/basis-unit-constants.rst
@@ -22,7 +22,7 @@ Context
     +----------------+               |
     |    bu_store    |               |
     +----------------+---------------+
-    |cYEL       basis_unit           |
+    |cBLU       basis_unit           |
     +--------------------------------+
     |            dimension           |
     +--------------------------------+

diff --git a/docs/basis-unit-reference.rst b/docs/basis-unit-reference.rst
@@ -19,7 +19,7 @@ Built-in named units for each native dimension
     +----------------+               |
     |    bu_store    |               |
     +----------------+---------------+
-    |cYEL       basis_unit           |
+    |cBLU       basis_unit           |
     +--------------------------------+
     |            dimension           |
     +--------------------------------+

diff --git a/docs/bpu-class.rst b/docs/bpu-class.rst
@@ -18,7 +18,7 @@ Context
     +--------------------------------+
     |         natural_unit           |
     +--------------------------------+
-    |cYEL           bpu              |
+    |cBLU           bpu              |
     +----------------+               |
     |    bu_store    |               |
     +----------------+---------------+

diff --git a/docs/bu-store-class.rst b/docs/bu-store-class.rst
@@ -15,7 +15,7 @@ Basis Unit Store
     +--------------------------------+
     |               bpu              |
     +----------------+               |
-    |cYEL bu_store   |               |
+    |cBLU bu_store   |               |
     +----------------+---------------+
     |           basis_unit           |
     +--------------------------------+

diff --git a/docs/conf.py b/docs/conf.py
@@ -15,6 +15,7 @@
 
 #extensions = []
 extensions = [ "breathe",
+               "sphinx.ext.mathjax",     # inline math
                "sphinx.ext.autodoc",     # generate info from docstrings
                "sphinxcontrib.ditaa",    # diagrams-through-ascii-art
                "sphinxcontrib.plantuml"  # text -> uml diagrams

diff --git a/docs/dimension-enum.rst b/docs/dimension-enum.rst
@@ -24,7 +24,7 @@ Context
     +----------------+---------------+
     |           basis_unit           |
     +--------------------------------+
-    |cYEL        dimension           |
+    |cBLU        dimension           |
     +--------------------------------+
 
 Introduction

diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -4,26 +4,35 @@ Glossary
 --------
 
 .. glossary::
-    basis dimension
-      Orthogonal directions associated with basis units,  for example *mass*, *length*, *time*.
-      In xo-unit these are represented by the enum ``xo::qty::dim``.
-
-    basis unit (bu)
-      An implementation type representing a quantity (with associated scale) in the direction of a single :term:`basis dimension`.
-      For example *milliseconds*, *seconds*, and *hours* stand for different basis units with the *time* dimension.
-      In xo-unit these are represented by the template type ``xo::qty::basis_unit``.
-
+    dimension
+    dim
+      | Fundamental, orthogonal directions associated available for constructing units.
+      | For example *mass*, *length*, *time*.
+      | In *xo-unit* these are represented by the enum :doc:`xo::qty::dimension<dimension-enum>`.
+
+    basis unit
+    bu
+      | An implementation type representing a quantity (with associated scale) in the direction of a single :term:`dimension`.
+      | For example *milliseconds*, *seconds*, and *hours* stand for different basis units within the *time* dimension.
+      | In *xo-unit* these are represented by the template type :doc:`xo::qty::basis_unit<basis-unit-class>`.
+
+    basis power unit
     bpu
-      A rational power of a (single) basis unit.  For example *s\ :sup:-2* or *hr\ :sup:-(1/2)*.
-      In xo-unit these are represented by the template type ``xo::qty::bpu``.
-
-    natural unit (nu)
-      A cartesian product of basis power units (bpus).  For example *kg.m.s\ :sup:-2* or *hr\ :sup:-(1/2)*.
-      In xo-unit these are represented by template type ``xo::qty::natural_unit``.
-
-    scaled unit (su)
-      A dimensionless multiple of a natural unit.  Used as intermediate value when coalescing quantities involving different units.
-      In xo-unit these are represented by template type ``xo::qty::scaled_unit``.
+      | A rational power of a (single) basis unit.
+      | For example :math:`s^{-2}` for unit "per second squared" or :math:`yr^{-(1/2)}` for "per square-root of a year".
+      | In *xo-unit* these are represented by the template type :doc:`xo::qty::bpu<bpu-class>`
+
+    natural unit
+    nu
+      | A cartesian product of basis power units (bpus);
+      | For example :math:`kg.m.s^{-2}` or :math:`hr^{-(1/2)}`.
+      | In *xo-unit* these are represented by template type :doc:`xo::qty::natural_unit<natural-unit-class>`.
+
+    scaled unit
+    su
+      | A dimensionless multiple of a natural unit.
+      | Used as intermediate value when coalescing quantities involving different units.
+      | In *xo-unit* these are represented by template type :doc:`xo::qty::scaled_unit<scaled-unit-class>`.
 
     XO
       A set of integrated c++ libraries for complex event processing, with browser and python integration.

diff --git a/docs/implementation.rst b/docs/implementation.rst
@@ -3,7 +3,7 @@
 Components
 ==========
 
-Library dependencies for *xo-unit*:
+Library dependency tower for *xo-unit*:
 
 .. ditaa::
 
@@ -14,28 +14,31 @@ Library dependencies for *xo-unit*:
     +-----------------+
     |  xo_flatstring  |
     +-----------------+
+    |    xo_cmake     |
+    +-----------------+
 
-``xo-unit`` also depends on ``xo-cmake`` macros.
+Install instructions :doc:`here<install>`
 
 Abstraction tower for *xo-unit* components:
 
 .. ditaa::
-
-    +-----------+-----------+
-    |  quantity | xquantity |
-    +-----------+-----------+
-    |      scaled_unit      |
-    +-----------------------+
-    |     natural_unit      |
-    +-----------------------+
-    |          bpu          |
-    +-----------+           |
-    |  bu_store |           |
-    +-----------+-----------+
-    |       basis_unit      |
-    +-----------------------+
-    |       dimension       |
-    +-----------------------+
+    :--scale: 0.85
+
+    +----------------+---------------+
+    |     quantity   |   xquantity   |
+    +----------------+---------------+
+    |          scaled_unit           |
+    +--------------------------------+
+    |         natural_unit           |
+    +--------------------------------+
+    |               bpu              |
+    +----------------+               |
+    |    bu_store    |               |
+    +----------------+---------------+
+    |           basis_unit           |
+    +--------------------------------+
+    |            dimension           |
+    +--------------------------------+
 
 - :doc:`quantity<quantity-reference>`:
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -28,7 +28,7 @@ runtime (since we can't construct new c++ types at runtime).
 
 .. toctree::
    :maxdepth: 2
-   :caption: xo-unit contents:
+   :caption: xo-unit contents
 
    install
    examples
@@ -42,10 +42,7 @@ runtime (since we can't construct new c++ types at runtime).
    basis-unit-reference
    dimension-enum
    development
-
-Indices and Tables
-------------------
-
-* :ref:`glossary`
-* :ref:`genindex`
-* :ref:`search`
+   ubuntu-github-workflow
+   glossary
+   genindex
+   search
diff --git a/docs/install.rst b/docs/install.rst
@@ -7,26 +7,35 @@ Install
 =======
 
 ``xo-unit`` uses supporting header-only libraries ``xo-ratio`` and ``xo-flatstring``.
-All three are on github:
+and (optionally) cmake macros ``xo-cmake``.  These are on github:
 
-- `xo-unit source`_
-- `xo-ratio source`_
-- `xo-flatstring source`_
+- `xo-unit source`_ (constexpr quantities, units and dimension-checking)
+- `xo-ratio source`_ (constexpr exact ratios)
+- `xo-flatstring source`_ (constexpr strings)
+- `xo-cmake source`_ (shared cmake macros)
 
 .. _xo-unit source: https://github.com/rconybea/xo-unit
 .. _xo-ratio source: https://github.com/rconybea/xo-ratio
 .. _xo-flatstring source: https://github.com/rconybea/xo-flatstring
+.. _xo-cmake source: https://github.com/rconybea/xo-cmake
 
-Implementation relies on some c++20 features (for example class-instances as template arguments).
-Tested with gcc 12.3, 13.2
+`xo-cmake` is nccessary to invoke `xo` cmake build for:
 
-``xo-unit`` also relies on sister header-only libraries:
+-  site install
+-  example programs
+-  unit tests
 
-One way to use ``xo-unit`` in a project is to import the source tree directly:
+Can omit to instead copy `xo_unit`, `xo-ratio` and `xo-flatstring` source trees;
+see instructions below for including as git submodule
+
+Implementation relies on some c++20 features (for example class-instances as template arguments).
+Tested with gcc 12.3, 13.2
 
 Include as submodule
 --------------------
 
+One way to use ``xo-unit`` in a project is to import the source tree directly:
+
 .. code-block:: bash
 
    cd myproject
@@ -50,21 +59,18 @@ to c++ source files that rely on xo-unit
 Ubuntu Install Pattern
 ----------------------
 
-Example instructions (from github actions CI) for build starting from stock ubuntu are in `ubuntu-main.yml`_
-
-.. _ubuntu-main.yml: https://github.com/Rconybea/xo-unit/blob/main/.github/workflows/ubuntu-main.yml
-
+:doc:`Example instructions<ubuntu-github-workflow>` (used for github actions CI) for build starting from stock ubuntu
 
 Installing from source
 ----------------------
 
-Although the xo-unit, xo-ratio and xo-flatstring libraries are header-only,
-they do have a build dependency on shared cmake macros,  and a bootstrap script `xo-cmake-config`.
+Install scripts for `xo-unit`, `xo-ratio` and `xo-flatstring` depend on shared cmake macros
+and a bootstrap script `xo-cmake-config`.
 
 * `xo-cmake`_ source
 
 .. _xo-cmake: https://github.com/rconybea/xo-cmake
-  
+
 Preamble:
 
 .. code-block:: bash
@@ -183,7 +189,7 @@ Preamble:
    git clone https://github.com/rconybea/xo-unit
 
    PREFIX=~/local  # ..or other desired installation prefix
-                
+
 Build and Install `catch2` (assuming ubuntu here):
 
 .. code-block:: bash
@@ -216,7 +222,7 @@ Build and Install `xo-randomgen` (no unit tests yet):
     cmake --build xo-randomgen/.build -j
     cmake --install xo-randomgen/.build
 
-Build, Test and Install `xo-flatstring`:    
+Build, Test and Install `xo-flatstring`:
 
 .. code-block:: bash
 
@@ -255,7 +261,7 @@ To enable building example programs:
 
     cd ~/proj/xo
     cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -DXO_ENABLE_EXAMPLES=1 -B xo-unit/.build -S xo-unit
-    
+
 Run examples from the build directory:
 
 .. code-block:: bash
@@ -288,17 +294,16 @@ Preamble (assuming ubuntu here):
     sudo apt-get install python3-sphinx-rtd-theme
     sudo apt-get install python3-breathe
 
-Build `xo-unit` docs 
+Build `xo-unit` docs
 
 .. code-block:: bash
 
     cd ~/proj/xo
     cmake -DCMAKE_INSTALL_PREFIX=$PREFIX -B xo-unit/.build
-    cmake --build xo-unit/.build -- docs                
+    cmake --build xo-unit/.build -- docs
     cmake --install xo-unit/.build   # if docs built,  installs to $PREFIX/share/doc/xo_unit/html
 
 Supported compilers
 -------------------
 
 * developed with gcc 12.3.0 and gcc 13.2.0;  github CI using gcc 11.4.0 (asof March 2024)
-
diff --git a/docs/natural-unit-class.rst b/docs/natural-unit-class.rst
@@ -16,7 +16,7 @@ Context
     +----------------+---------------+
     |          scaled_unit           |
     +--------------------------------+
-    |cYEL     natural_unit           |
+    |cBLU     natural_unit           |
     +--------------------------------+
     |               bpu              |
     +----------------+               |
-Original file line number
+Diff line change
@@ Expand Up / @@ -15,7 +15,7 @@ Basis Unit Store @@
         +--------------------------------+
         |               bpu              |
         +----------------+               |
-        |cYEL bu_store   |               |
+        |cBLU bu_store   |               |
         +----------------+---------------+
         |           basis_unit           |
         +--------------------------------+
@@ Expand Down @@