xo-unit: docs improvements. Now using sphinxcontrib-ditaa
This commit is contained in:
parent
7d7a424a9f
commit
2a63780235
7 changed files with 267 additions and 48 deletions
|
|
@ -3,7 +3,7 @@
|
|||
xo_doxygen_collect_deps()
|
||||
xo_docdir_doxygen_config()
|
||||
xo_docdir_sphinx_config(
|
||||
index.rst examples.rst glossary.rst install.rst
|
||||
index.rst examples.rst glossary.rst install.rst abstractions.rst
|
||||
quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst
|
||||
unit-reference.rst unit-concept.rst unit-quantities.rst
|
||||
)
|
||||
|
|
|
|||
191
docs/abstractions.rst
Normal file
191
docs/abstractions.rst
Normal file
|
|
@ -0,0 +1,191 @@
|
|||
.. _abstractions:
|
||||
|
||||
Representation
|
||||
==============
|
||||
|
||||
.. ditaa::
|
||||
|
||||
+-----------+-----------+
|
||||
| quantity | xquantity |
|
||||
+-----------+-----------+
|
||||
| scaled_unit |
|
||||
+-----------------------+
|
||||
| natural_unit |
|
||||
+-----------------------+
|
||||
| bpu |
|
||||
+-----------------------+
|
||||
| basis_unit |
|
||||
+-----------------------+
|
||||
| dimension |
|
||||
+-----------------------+
|
||||
|
||||
- quantity: see :doc:`quantity-reference`
|
||||
|
||||
.. code-block:: cpp
|
||||
:linenos:
|
||||
:emphasize-lines: 6
|
||||
|
||||
#include "xo/unit/quantity.hpp"
|
||||
...
|
||||
namespace q = xo::qty::qty;
|
||||
|
||||
// 7.55km.min^-2
|
||||
quantity qty1 = 7.55 * q::kilometer / (q::minute * q::minute);
|
||||
|
||||
.. uml::
|
||||
:caption: representation for quantity 7.55km.min^-2
|
||||
:scale: 99%
|
||||
:align: center
|
||||
|
||||
object qty1<<quantity>>
|
||||
qty1 : scale = 7.55
|
||||
|
||||
rectangle {
|
||||
|
||||
object km_per_min2<<natural_unit>>
|
||||
km_per_min2 : n_bpu = 2
|
||||
km_per_min2 : bpu[0] = km
|
||||
km_per_min2 : bpu[1] = per_min
|
||||
|
||||
object km<<bpu>>
|
||||
km : native_dim = dim.mass
|
||||
km : scalefactor = 1000/1
|
||||
km : power = 1
|
||||
|
||||
object per_min2<<bpu>>
|
||||
per_min2 : native_dim = dim.time
|
||||
per_min2 : scalefactor = 60/1
|
||||
per_min2 : power = -2
|
||||
|
||||
qty1 o-- km_per_min2 : s_unit (static constexpr)
|
||||
|
||||
km_per_min2 *-- km
|
||||
km_per_min2 *-- per_min2
|
||||
|
||||
}
|
||||
|
||||
.. code-block:: cpp
|
||||
:linenos:
|
||||
|
||||
// 123ng
|
||||
quantity qty2 = q::nanograms(123);
|
||||
|
||||
.. uml::
|
||||
:caption: representation for quantity 123 nanograms
|
||||
:scale: 99%
|
||||
:align: center
|
||||
|
||||
object qty2<<quantity>>
|
||||
qty2 : scale = 123
|
||||
|
||||
rectangle {
|
||||
|
||||
object ng_unit<<natural_unit>>
|
||||
ng_unit : n_bpu = 1
|
||||
ng_unit : bpu[0] = ng
|
||||
|
||||
object ng<<bpu>>
|
||||
ng : native_dim = dim::mass
|
||||
ng : scalefactor = 1/10^9
|
||||
ng : power = 1
|
||||
|
||||
qty2 o-- ng_unit : s_unit (static constexpr)
|
||||
|
||||
ng_unit *-- ng
|
||||
|
||||
}
|
||||
|
||||
.. code-block:: cpp
|
||||
:linenos:
|
||||
|
||||
// (123*7.55) ng.km.min^-2
|
||||
quantity qty3 = qty2 * qty1;
|
||||
|
||||
.. uml::
|
||||
:caption: quantity 928.65 ng.km.min^-2
|
||||
:scale: 99%
|
||||
:align: center
|
||||
|
||||
object qty3<<quantity>>
|
||||
qty3 : scale = 928.65
|
||||
|
||||
rectangle {
|
||||
|
||||
object ng_km_min2_unit<<natural_unit>>
|
||||
ng_km_min2_unit : n_bpu = 3
|
||||
ng_km_min2_unit : bpu[0] = ng
|
||||
ng_km_min2_unit : bpu[1] = km
|
||||
ng_km_min2_unit : bpu[2] = per_min2
|
||||
|
||||
object ng<<bpu>>
|
||||
ng : native_dim = dim::mass
|
||||
ng : scalefactor = 1/10^9
|
||||
ng : power = 1
|
||||
|
||||
object km<<bpu>>
|
||||
km : native_dim = dim::distance
|
||||
km : scalefactor = 1000/1
|
||||
km : power = 1
|
||||
|
||||
object per_min2<<bpu>>
|
||||
per_min2 : native_dim = dim::time
|
||||
per_min2 : scalefactor = 60/1
|
||||
per_min2 : power = -2
|
||||
|
||||
qty3 o-- ng_km_min2_unit : s_unit (static constexpr)
|
||||
|
||||
ng_km_min2_unit *-- ng
|
||||
ng_km_min2_unit *-- km
|
||||
ng_km_min2_unit *-- per_min2
|
||||
}
|
||||
|
||||
.. code-block:: cpp
|
||||
:linenos:
|
||||
|
||||
namespace su = xo::qty::su;
|
||||
|
||||
// (123*7.55) ng.km.min^-2 ==> 2.57958e-10kg.m.s^-2
|
||||
|
||||
quantity qty3b = qty3.rescale_ext<su::kilogram * su::meter / (su::second * su::second)>();
|
||||
|
||||
.. uml::
|
||||
:caption: quantity 928.65 ng.km.min^-2
|
||||
:scale: 99%
|
||||
:align: center
|
||||
|
||||
object qty3b<<quantity>>
|
||||
qty3b : scale = 2.59758e-10
|
||||
|
||||
rectangle {
|
||||
|
||||
object kg_m_s2_unit<<natural_unit>>
|
||||
kg_m_s2_unit : n_bpu = 3
|
||||
kg_m_s2_unit : bpu[0] = kg
|
||||
kg_m_s2_unit : bpu[1] = m
|
||||
kg_m_s2_unit : bpu[2] = per_s2
|
||||
|
||||
object kg<<bpu>>
|
||||
kg : native_dim = dim::mass
|
||||
kg : scalefactor = 1000/1
|
||||
kg : power = 1
|
||||
|
||||
object m<<bpu>>
|
||||
m : native_dim = dim::distance
|
||||
m : scalefactor = 1/1
|
||||
m : power = 1
|
||||
|
||||
object per_s2<<bpu>>
|
||||
per_s2 : native_dim = dim::time
|
||||
per_s2 : scalefactor = 1/1
|
||||
per_s2 : power = -2
|
||||
|
||||
qty3b o-- kg_m_s2_unit : s_unit (static constexpr)
|
||||
|
||||
kg_m_s2_unit *-- kg
|
||||
kg_m_s2_unit *-- m
|
||||
kg_m_s2_unit *-- per_s2
|
||||
}
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Abstractions
|
||||
|
|
@ -15,7 +15,9 @@ author = 'Roland Conybeare'
|
|||
|
||||
#extensions = []
|
||||
extensions = [ "breathe",
|
||||
"sphinx.ext.autodoc" # generate info from docstrings
|
||||
"sphinx.ext.autodoc", # generate info from docstrings
|
||||
"sphinxcontrib.ditaa", # diagrams-through-ascii-art
|
||||
"sphinxcontrib.plantuml" # text -> uml diagrams
|
||||
]
|
||||
|
||||
# note: breathe requires doxygen xml output -> must have GENERATE_XML = YES in Doxyfile.in
|
||||
|
|
|
|||
|
|
@ -12,9 +12,11 @@ dimension checking and unit conversion.
|
|||
Functionality is similar in spirit to that provided by ``boost::units``;
|
||||
however there are some important differences:
|
||||
|
||||
* interchangeable compile-time / run-time unit representation.
|
||||
* streamlined implementation using c++20 features.
|
||||
* along with no-runtime-overhead compile-time unit inference,
|
||||
also provides defer-until-runtime representation.
|
||||
* constexpr string representation for things like unit abbreviations.
|
||||
* supports fractional dimensions, for concepts like volatility.
|
||||
* supports fractional dimensions, for concepts like volatility.
|
||||
* integration with python (see sister project xo-pyunit)
|
||||
|
||||
Second, ``xo-unit`` supports fractional dimensions. This allows using it to naturally handle
|
||||
|
|
@ -30,6 +32,7 @@ runtime (since we can't construct new c++ types at runtime).
|
|||
|
||||
install
|
||||
examples
|
||||
abstractions
|
||||
unit-quantities
|
||||
quantity-reference
|
||||
unit-reference
|
||||
|
|
|
|||
|
|
@ -8,29 +8,24 @@ Quantity
|
|||
#include <xo/unit/quantity.hpp>
|
||||
|
||||
The primary data structure for interacting with xo-unit is the
|
||||
template class ``xo::unit::quantity``.
|
||||
template class ``xo::qty::quantity``.
|
||||
|
||||
.. doxygenclass:: xo::unit::quantity
|
||||
.. doxygenclass:: xo::qty::quantity
|
||||
|
||||
Type Traits
|
||||
-----------
|
||||
|
||||
.. doxygengroup:: quantity-traits
|
||||
:content-only:
|
||||
.. doxygengroup:: quantity-type-traits
|
||||
|
||||
Constructors
|
||||
------------
|
||||
|
||||
.. doxygengroup:: quantity-ctors
|
||||
:content-only:
|
||||
|
||||
.. doxygengroup:: quantity-named-ctors
|
||||
:content-only:
|
||||
|
||||
The simplest way to create a quantity instance is to use either
|
||||
|
||||
* factory functions in ``xo::unit::qty``, see :doc:`quantity-factoryfunctions`
|
||||
* unit variables in ``xo::unit::units``, see :doc:`quantity-unitvars`
|
||||
* factory functions in ``xo::qty::qty``, see :doc:`quantity-factoryfunctions`
|
||||
* unit variables in ``xo::qty::qty``, see :doc:`quantity-unitvars`
|
||||
|
||||
Assignment
|
||||
----------
|
||||
|
|
|
|||
|
|
@ -10,18 +10,26 @@ Quantity Factory Functions
|
|||
|
||||
#include <xo/unit/quantity.hpp>
|
||||
|
||||
.. doxygenfunction:: xo::unit::qty::milligrams
|
||||
.. doxygenfunction:: xo::unit::qty::grams
|
||||
.. doxygenfunction:: xo::unit::qty::kilograms
|
||||
Mass
|
||||
----
|
||||
.. doxygenfunction:: xo::qty::qty::milligrams
|
||||
.. doxygenfunction:: xo::qty::qty::grams
|
||||
.. doxygenfunction:: xo::qty::qty::kilograms
|
||||
|
||||
.. doxygenfunction:: xo::unit::qty::millimeters
|
||||
.. doxygenfunction:: xo::unit::qty::meters
|
||||
.. doxygenfunction:: xo::unit::qty::kilometers
|
||||
Distance
|
||||
--------
|
||||
.. doxygenfunction:: xo::qty::qty::millimeters
|
||||
.. doxygenfunction:: xo::qty::qty::meters
|
||||
.. doxygenfunction:: xo::qty::qty::kilometers
|
||||
|
||||
.. doxygenfunction:: xo::unit::qty::nanoseconds
|
||||
.. doxygenfunction:: xo::unit::qty::microseconds
|
||||
.. doxygenfunction:: xo::unit::qty::milliseconds
|
||||
.. doxygenfunction:: xo::unit::qty::seconds
|
||||
.. doxygenfunction:: xo::unit::qty::minutes
|
||||
.. doxygenfunction:: xo::unit::qty::hours
|
||||
.. doxygenfunction:: xo::unit::qty::days
|
||||
.. doxygenfunction:: xo::qty::qty::inches
|
||||
|
||||
Time
|
||||
----
|
||||
.. doxygenfunction:: xo::qty::qty::nanoseconds
|
||||
.. doxygenfunction:: xo::qty::qty::microseconds
|
||||
.. doxygenfunction:: xo::qty::qty::milliseconds
|
||||
.. doxygenfunction:: xo::qty::qty::seconds
|
||||
.. doxygenfunction:: xo::qty::qty::minutes
|
||||
.. doxygenfunction:: xo::qty::qty::hours
|
||||
.. doxygenfunction:: xo::qty::qty::days
|
||||
|
|
|
|||
|
|
@ -10,36 +10,56 @@ Quantity Unit Variables
|
|||
|
||||
#include <xo/unit/quantity.hpp>
|
||||
|
||||
The ``xo::unit::unit_qty`` namespace contains unit quantities in each dimension.
|
||||
Can use these to request unit conversion involving multiple dimensions, for example:
|
||||
The ``xo::qty::qty`` namespace contains unit quantities in each dimension.
|
||||
Can use these to assemble unit quantities with compound dimensions
|
||||
|
||||
.. code-block:: cpp
|
||||
:linenos:
|
||||
:emphasize-lines: 6
|
||||
|
||||
namespace qty = xo::unit::qty;
|
||||
namespace u = xo::unit::unit_qty;
|
||||
#include "xo/unit/quantity.hpp"
|
||||
|
||||
auto q1 = (qty::kilometers(150.0) / qty::hours(0.5);
|
||||
auto q2 = q1.with_units_from(u:meter / u:second);
|
||||
namespace q = xo::qty::qty;
|
||||
|
||||
auto q1 = (q::kilometers(150.0) / q::hours(0.5));
|
||||
constexpr auto u_mps = q:meter / q:second;
|
||||
auto q2 = with_units_from(q1, u_mps);
|
||||
|
||||
|
||||
Mass
|
||||
----
|
||||
.. doxygenvariable:: xo::unit::unit_qty::milligram
|
||||
.. doxygenvariable:: xo::unit::unit_qty::gram
|
||||
.. doxygenvariable:: xo::unit::unit_qty::kilogram
|
||||
.. doxygenvariable:: xo::qty::qty::milligram
|
||||
.. doxygenvariable:: xo::qty::qty::gram
|
||||
.. doxygenvariable:: xo::qty::qty::kilogram
|
||||
.. doxygenvariable:: xo::qty::qty::tonne
|
||||
.. doxygenvariable:: xo::qty::qty::kilotonne
|
||||
|
||||
Distance
|
||||
--------
|
||||
.. doxygenvariable:: xo::unit::unit_qty::millimeter
|
||||
.. doxygenvariable:: xo::unit::unit_qty::meter
|
||||
.. doxygenvariable:: xo::unit::unit_qty::kilometer
|
||||
.. doxygenvariable:: xo::qty::qty::picometer
|
||||
.. doxygenvariable:: xo::qty::qty::nanometer
|
||||
.. doxygenvariable:: xo::qty::qty::micrometer
|
||||
.. doxygenvariable:: xo::qty::qty::millimeter
|
||||
.. doxygenvariable:: xo::qty::qty::meter
|
||||
.. doxygenvariable:: xo::qty::qty::kilometer
|
||||
.. doxygenvariable:: xo::qty::qty::megameter
|
||||
.. doxygenvariable:: xo::qty::qty::gigameter
|
||||
.. doxygenvariable:: xo::qty::qty::lightsecond
|
||||
.. doxygenvariable:: xo::qty::qty::astronomicalunit
|
||||
|
||||
Time
|
||||
----
|
||||
.. doxygenvariable:: xo::unit::unit_qty::nanosecond
|
||||
.. doxygenvariable:: xo::unit::unit_qty::microsecond
|
||||
.. doxygenvariable:: xo::unit::unit_qty::millisecond
|
||||
.. doxygenvariable:: xo::unit::unit_qty::second
|
||||
.. doxygenvariable:: xo::unit::unit_qty::minute
|
||||
.. doxygenvariable:: xo::unit::unit_qty::hour
|
||||
.. doxygenvariable:: xo::unit::unit_qty::day
|
||||
.. notyet .. doxygenvariable:: xo::qty::qty::picosecond
|
||||
.. notyet .. doxygenvariable:: xo::qty::qty::nanosecond
|
||||
.. notyet .. doxygenvariable:: xo::qty::qty::microsecond
|
||||
.. notyet .. doxygenvariable:: xo::qty::qty::millisecond
|
||||
.. doxygenvariable:: xo::qty::qty::second
|
||||
.. doxygenvariable:: xo::qty::qty::minute
|
||||
.. doxygenvariable:: xo::qty::qty::hour
|
||||
.. doxygenvariable:: xo::qty::qty::day
|
||||
.. notyet doxygenvariable:: xo::qty::qty::week
|
||||
.. notyet doxygenvariable:: xo::qty::qty::month
|
||||
.. notyet doxygenvariable:: xo::qty::qty::year
|
||||
.. notyet doxygenvariable:: xo::qty::qty::year250
|
||||
.. notyet doxygenvariable:: xo::qty::qty::year360
|
||||
.. notyet doxygenvariable:: xo::qty::qty::year365
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue