docs: examples chapter reorganized

docs/CMakeLists.txt

@@ -54,15 +54,29 @@ set(unitsSphinxDocs
     "${CMAKE_CURRENT_SOURCE_DIR}/design/quantity_kind.rst"
 
     "${CMAKE_CURRENT_SOURCE_DIR}/examples.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/avg_speed.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/box_example.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/capacitor_time_curve.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/clcpp_response.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/conversion_factor.rst"
+
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics/avg_speed.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics/box_example.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics/capacitor_time_curve.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics/clcpp_response.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics/experimental_angle.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics/foot_pound_second.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics/glide_computer.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics/hello_units.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics/total_energy.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/basics/unknown_dimension.rst"
+
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/custom_representation.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/custom_representation/linear_algebra.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/custom_representation/measurement.rst"
+
     "${CMAKE_CURRENT_SOURCE_DIR}/examples/custom_systems.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/foot_pound_second.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/glide_computer.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/hello_units.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/custom_systems/custom_systems.rst"
+
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/custom_utilities.rst"
+    "${CMAKE_CURRENT_SOURCE_DIR}/examples/custom_utilities/conversion_factor.rst"
+
     "${CMAKE_CURRENT_SOURCE_DIR}/examples/kalman_filter.rst"
     "${CMAKE_CURRENT_SOURCE_DIR}/examples/kalman_filter/example_1.rst"
     "${CMAKE_CURRENT_SOURCE_DIR}/examples/kalman_filter/example_2.rst"
@@ -73,10 +87,6 @@ set(unitsSphinxDocs
     "${CMAKE_CURRENT_SOURCE_DIR}/examples/kalman_filter/example_7.rst"
     "${CMAKE_CURRENT_SOURCE_DIR}/examples/kalman_filter/example_8.rst"
     "${CMAKE_CURRENT_SOURCE_DIR}/examples/kalman_filter/kalman.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/linear_algebra.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/measurement.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/total_energy.rst"
-    "${CMAKE_CURRENT_SOURCE_DIR}/examples/unknown_dimension.rst"
 
     "${CMAKE_CURRENT_SOURCE_DIR}/faq.rst"
 

docs/examples.rst

@@ -2,22 +2,10 @@ Examples
 ========
 
 .. toctree::
-    :maxdepth: 1
-
-    examples/hello_units
-    examples/avg_speed
-    examples/box_example
-    examples/unknown_dimension
-    examples/measurement
-    examples/linear_algebra
-    examples/foot_pound_second
-    examples/custom_systems
-    examples/glide_computer
-
-    examples/capacitor_time_curve
-    examples/clcpp_response
-    examples/conversion_factor
-    examples/experimental_angle
-    examples/total_energy
+    :maxdepth: 2
 
+    examples/basics
     examples/kalman_filter
+    examples/custom_representation
+    examples/custom_systems
+    examples/custom_utilities

docs/examples/basics.rst

@@ -0,0 +1,18 @@
+Basics
+======
+
+The following examples highlight the basics of the library design.
+
+.. toctree::
+    :maxdepth: 1
+
+    basics/hello_units
+    basics/clcpp_response
+    basics/avg_speed
+    basics/box_example
+    basics/capacitor_time_curve
+    basics/unknown_dimension
+    basics/foot_pound_second
+    basics/experimental_angle
+    basics/total_energy
+    basics/glide_computer

docs/examples/custom_representation.rst

@@ -0,0 +1,10 @@
+Custom Representation Types
+===========================
+
+The following examples show how to work with custom represenation types.
+
+.. toctree::
+    :maxdepth: 1
+
+    custom_representation/measurement
+    custom_representation/linear_algebra

docs/examples/custom_systems.rst

@@ -1,7 +1,9 @@
-custom_systems
+Custom Systems
 ==============
 
-.. literalinclude:: ../../example/custom_systems.cpp
-  :caption: custom_systems.cpp
-  :start-at: #include
-  :linenos:
+The following examples show how to define custom systems of units and quantities.
+
+.. toctree::
+    :maxdepth: 1
+
+    custom_systems/custom_systems

docs/examples/custom_systems/custom_systems.rst

@@ -0,0 +1,7 @@
+custom_systems
+==============
+
+.. literalinclude:: ../../example/custom_systems.cpp
+  :caption: custom_systems.cpp
+  :start-at: #include
+  :linenos:

docs/examples/custom_utilities.rst

@@ -0,0 +1,9 @@
+Custom Utilites
+===============
+
+The following examples present how to reuse library facilities to create custom utilities.
+
+.. toctree::
+    :maxdepth: 1
+
+    custom_utilities/conversion_factor