mpusz/mp-units
1
0
Fork 1
mirror of https://github.com/mpusz/mp-units.git synced 2026-05-05 12:24:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Hwo-to Guides directory structure refactored

Browse Source
This commit is contained in:
Mateusz Pusz
2026-01-25 22:58:22 +01:00
parent f097d96946
commit 6703f3e835
20 changed files with 103 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/blog/posts/2.1.0-released.md
+1 -1
View File
@@ -130,7 +130,7 @@ We've also introduced an innovative approach that allows us to specify if such
conversions should happen implicitly or if they need to be forced explicitly.
More on this subject can be found in the [Interoperability with Other
Libraries](../../how_to_guides/interoperability_with_other_libraries.md)
Libraries](../../how_to_guides/integration/interoperability_with_other_libraries.md)
chapter.
docs/blog/posts/2.2.0-released.md
+1 -1
View File
@@ -143,7 +143,7 @@ code like the below anymore:
Additionally, we merged all of the compatibility-related macros into one header
file `mp-units/compat_macros.h`. This header file should be explicitly included
before importing C++ modules if we want to benefit from the
[Wide Compatibility tools](../../how_to_guides/wide_compatibility.md).
[Wide Compatibility tools](../../how_to_guides/integration/wide_compatibility.md).
## Better control over the library's API
docs/examples/hello_units.md
+1 -1
View File
@@ -115,7 +115,7 @@ Both stream insertion operations and `std::format` facilities are supported.
support `std::format` or a user prefers to use the `{fmt}` library, this macro will
resolve to `fmt` namespace. Otherwise, the `std` namespace will be used.
More about it can be found in the [Wide Compatibility](../how_to_guides/wide_compatibility.md#mp_units_std_fmt)
More about it can be found in the [Wide Compatibility](../how_to_guides/integration/wide_compatibility.md#mp_units_std_fmt)
chapter.
## Related Concepts
docs/examples/index.md
+2 -1
View File
@@ -16,7 +16,8 @@ These examples:
- ✅ Range from beginner to advanced complexity
- ✅ Are organized by level, system, feature, and domain
- ✅ Work with all [supported compilers](../getting_started/cpp_compiler_support.md)
- ✅ Use [Wide Compatibility](../how_to_guides/wide_compatibility.md) mode for maximum portability
- ✅ Use [Wide Compatibility](../how_to_guides/integration/wide_compatibility.md) mode for
maximum portability
**Prerequisites**: Basic familiarity with **mp-units** from [Tutorials](../tutorials/index.md).
Beginner examples include detailed explanations; intermediate and advanced examples assume
docs/getting_started/cpp_compiler_support.md
+5 -4
View File
@@ -7,7 +7,7 @@
Even though the library benefits from the latest C++ versions (if available), C++20 is enough
to compile and use all of the library's functionality. Newer features can be hidden behind
some [preprocessor macros](../how_to_guides/wide_compatibility.md#compatibility-macros)
some [preprocessor macros](../how_to_guides/integration/wide_compatibility.md#compatibility-macros)
providing a backward-compatible way to use them.
The table below provides the minimum compiler version required to compile the code using
@@ -63,7 +63,7 @@ a specific C++ feature:
- the customer's project did not switch to `std::format` yet (even when the compiler
supports it).
- To write code with wide compatibility a
[dedicated macro may be used](../how_to_guides/wide_compatibility.md#mp_units_std_fmt).
[dedicated macro may be used](../how_to_guides/integration/wide_compatibility.md#mp_units_std_fmt).
- Tested with `__cpp_lib_format` [feature test macro](https://en.cppreference.com/w/cpp/feature_test).
- Related build options:
- Conan: [std_format](installation_and_usage.md#std_format)
@@ -104,9 +104,10 @@ a specific C++ feature:
- This feature removes the need for the usage of the CRTP idiom in the
[`quantity_spec` definitions](../users_guide/framework_basics/systems_of_quantities.md#defining-quantities).
- To write code with wide compatibility
a [dedicated macro may be used](../how_to_guides/wide_compatibility.md#QUANTITY_SPEC).
a [dedicated macro may be used](../how_to_guides/integration/wide_compatibility.md#QUANTITY_SPEC).
- Tested with `__cpp_explicit_this_parameter` [feature test macro](https://en.cppreference.com/w/cpp/feature_test).
- Note that some compiler versions do not implement this macro even though they do support the
- Note that some compiler versions do not implement this macro even though they do
support the
feature well enough. In such cases, compilation with explicit `this` is enforced.
- Related build options:
- Conan: [no_crtp](installation_and_usage.md#no_crtp)
docs/getting_started/project_structure.md
+1 -1
View File
@@ -90,7 +90,7 @@ All of the project's header files can be found in the `mp-units/...` subdirector
- `mp-units/math.h` provides overloads of common math functions for quantities,
- `mp-units/random.h` provides C++ pseudo-random number generators for quantities,
- `mp-units/compat_macros.h` provides macros for
[wide compatibility](../how_to_guides/wide_compatibility.md).
[wide compatibility](../how_to_guides/integration/wide_compatibility.md).
??? info "More details"
docs/how_to_guides/advanced_usage/index.md
+20
View File
@@ -0,0 +1,20 @@
# Advanced Usage
Advanced techniques for using **mp-units** in sophisticated scenarios beyond standard
quantity calculations.
## Available Guides
<!-- markdownlint-disable MD013 -->
- [Pure Dimensional Analysis](pure_dimensional_analysis.md) - Use dimensions without specific units for symbolic computation, compile-time validation, and custom arithmetic types
<!-- markdownlint-enable MD013 -->
## When to Use These Guides?
Use these advanced techniques when you:
- Need dimensional analysis without actual quantity values
- Build symbolic computation or automatic differentiation systems
- Validate dimensional consistency at compile-time
- Work with template metaprogramming involving dimensions
- Implement custom arithmetic types with dimensional correctness
docs/how_to_guides/pure_dimensional_analysis.md → docs/how_to_guides/advanced_usage/pure_dimensional_analysis.md
+1 -1
View File
@@ -239,7 +239,7 @@ throughout the computation.
## Real-World Example: Kalman Filter
The library includes a complete [Kalman filter example](../examples/kalman_filter.md)
The library includes a complete [Kalman filter example](../../examples/kalman_filter.md)
demonstrating pure dimensional analysis in a practical application. The implementation
uses dimensions to enforce compile-time constraints on state variables:
docs/how_to_guides/index.md
+9 -6
View File
@@ -20,13 +20,16 @@ fundamentals, then refer to these guides when you need to solve specific problem
## Available Guides
### Working with the Library
### [Advanced Usage](advanced_usage/index.md)
Advanced techniques and patterns for sophisticated scenarios beyond standard quantity
calculations.
### [Integration](integration/index.md)
Guides for integrating **mp-units** with existing codebases, custom types, third-party
libraries, and various compiler environments.
- [Pure Dimensional Analysis](pure_dimensional_analysis.md) - Use dimensions without specific units
- [Working with Legacy Interfaces](working_with_legacy_interfaces.md) - Integrate with existing code
- [Using Custom Representation Types](using_custom_representation_types.md) - Define custom numeric types
- [Interoperability with Other Libraries](interoperability_with_other_libraries.md) - Work with third-party libraries
- [Wide Compatibility](wide_compatibility.md) - Maximize portability across compilers
## When to Use How-to Guides?
docs/how_to_guides/integration/index.md
+24
View File
@@ -0,0 +1,24 @@
# Integration
Guides for integrating **mp-units** with existing codebases, custom types, third-party
libraries, and various compiler environments.
## Available Guides
<!-- markdownlint-disable MD013 -->
- [Working with Legacy Interfaces](working_with_legacy_interfaces.md) - Integrate with existing code that uses raw numeric types
- [Using Custom Representation Types](using_custom_representation_types.md) - Define custom numeric types as quantity representations
- [Interoperability with Other Libraries](interoperability_with_other_libraries.md) - Work with third-party libraries and frameworks
- [Wide Compatibility](wide_compatibility.md) - Maximize portability across different compilers and environments
<!-- markdownlint-enable MD013 -->
## When to Use These Guides?
Use these integration guides when you:
- Need to integrate mp-units into existing codebases
- Work with legacy APIs expecting raw numeric types
- Want to use custom numeric types (fixed-point, arbitrary precision, etc.)
- Need interoperability with other libraries
- Target multiple compilers or environments
- Require maximum portability and compatibility
docs/how_to_guides/interoperability_with_other_libraries.md → docs/how_to_guides/integration/interoperability_with_other_libraries.md
+3 -3
View File
@@ -86,7 +86,7 @@ struct mp_units::quantity_like_traits<Meter> {
};
```
After that, we can check that the [`QuantityLike`](../users_guide/framework_basics/concepts.md#QuantityLike)
After that, we can check that the [`QuantityLike`](../../users_guide/framework_basics/concepts.md#QuantityLike)
concept is satisfied:
```cpp
@@ -174,7 +174,7 @@ struct Timestamp {
};
```
As we described in [The Affine Space](../users_guide/framework_basics/the_affine_space.md) chapter, timestamps
As we described in [The Affine Space](../../users_guide/framework_basics/the_affine_space.md) chapter, timestamps
should be modeled as quantity points rather than regular quantities.
To allow the conversion between our custom `Timestamp` type and the `quantity_point` class
@@ -208,7 +208,7 @@ struct mp_units::quantity_point_like_traits<Timestamp> {
};
```
After that, we can check that the [`QuantityPointLike`](../users_guide/framework_basics/concepts.md#QuantityPointLike)
After that, we can check that the [`QuantityPointLike`](../../users_guide/framework_basics/concepts.md#QuantityPointLike)
concept is satisfied:
```cpp
docs/how_to_guides/using_custom_representation_types.md → docs/how_to_guides/integration/using_custom_representation_types.md
+7 -7
View File
@@ -31,7 +31,7 @@ of quantities.
Quantities in physics have different mathematical natures that determine which operations
make sense for them. For detailed information, see
[Character of a Quantity](../users_guide/framework_basics/character_of_a_quantity.md).
[Character of a Quantity](../../users_guide/framework_basics/character_of_a_quantity.md).
The character is defined at the **quantity specification** level:
@@ -75,7 +75,7 @@ quantity q8 = isq::displacement(vec{1., 2., 3.} * m); // ✅ OK: same as above
## Representation Requirements
To be used as a representation type in **mp-units**, a type must satisfy the
[`RepresentationOf`](../users_guide/framework_basics/concepts.md#RepresentationOf) concept.
[`RepresentationOf`](../../users_guide/framework_basics/concepts.md#RepresentationOf) concept.
The library supports different types of representations corresponding to different
quantity characters.
@@ -295,7 +295,7 @@ constexpr bool mp_units::treat_as_floating_point<my_fixed_point_type> = true;
```
**Impact:** When `treat_as_floating_point<Rep>` is `true`, the type is treated as floating-point
for conversion purposes. See [Value Conversions](../users_guide/framework_basics/value_conversions.md#value-conversions)
for conversion purposes. See [Value Conversions](../../users_guide/framework_basics/value_conversions.md#value-conversions)
for details on how this affects implicit conversions between quantities
---
@@ -433,7 +433,7 @@ quantity z = impedance * si::ohm; // Complex impedance
};
```
This is used in the [glide computer example](../examples/glide_computer.md#geographic-integration)
This is used in the [glide computer example](../../examples/glide_computer.md#geographic-integration)
for _latitude_ and _longitude_:
```cpp
@@ -732,9 +732,9 @@ that **mp-units** provides.
<!-- markdownlint-disable MD013 -->
**Related Documentation:**
- [Character of a Quantity](../users_guide/framework_basics/character_of_a_quantity.md) - Understanding quantity characters
- [Value Conversions](../users_guide/framework_basics/value_conversions.md) - How `treat_as_floating_point` affects conversions
- [Concepts](../users_guide/framework_basics/concepts.md#RepresentationOf) - The `RepresentationOf` concept definition
- [Character of a Quantity](../../users_guide/framework_basics/character_of_a_quantity.md) - Understanding quantity characters
- [Value Conversions](../../users_guide/framework_basics/value_conversions.md) - How `treat_as_floating_point` affects conversions
- [Concepts](../../users_guide/framework_basics/concepts.md#RepresentationOf) - The `RepresentationOf` concept definition
**Implementation References:**
docs/how_to_guides/wide_compatibility.md → docs/how_to_guides/integration/wide_compatibility.md
+3 -3
View File
@@ -10,9 +10,9 @@ special preprocessor macros that can be used to ensure the wide compatibility of
!!! note
Those macros are used in our short [example applications](../examples/index.md)
Those macros are used in our short [example applications](../../examples/index.md)
as those are meant to be built on all of
[the supported compilers](../getting_started/cpp_compiler_support.md). Some still
[the supported compilers](../../getting_started/cpp_compiler_support.md). Some still
do not support `std::format`, C++ modules, or C++ versions newer than C++20.
@@ -151,7 +151,7 @@ use [fmtlib](https://github.com/fmtlib/fmt) as their primary formatting facility
to benefit from additional features provided with the library).
This macro resolves to either the `std` or `fmt` namespace, depending on the value of
[MP_UNITS_API_STD_FORMAT](../getting_started/installation_and_usage.md#MP_UNITS_API_STD_FORMAT)
[MP_UNITS_API_STD_FORMAT](../../getting_started/installation_and_usage.md#MP_UNITS_API_STD_FORMAT)
CMake option.
To include the header files of the underlying text formatting framework, the following include
docs/how_to_guides/working_with_legacy_interfaces.md → docs/how_to_guides/integration/working_with_legacy_interfaces.md
+1 -1
View File
@@ -1,7 +1,7 @@
# Working with Legacy Interfaces
When working with legacy or unsafe interfaces, you may need to extract the
[numerical value of a quantity](../reference/glossary.md#numerical-value) and pass it to
[numerical value of a quantity](../../reference/glossary.md#numerical-value) and pass it to
third-party APIs that don't use type-safe units.
**mp-units** provides several member functions to safely bridge this gap while maintaining
docs/users_guide/framework_basics/systems_of_quantities.md
+1 -1
View File
@@ -123,7 +123,7 @@ type from a suitable instantiation.
[explicit object parameter](https://en.cppreference.com/w/cpp/language/member_functions#Explicit_object_parameter)
added in C++23 to remove the need for CRTP idiom, which significantly simplifies the code.
However, as C++23 is far from being mainstream today,
a [portability macro `QUANTITY_SPEC()`](../../how_to_guides/wide_compatibility.md#QUANTITY_SPEC)
a [portability macro `QUANTITY_SPEC()`](../../how_to_guides/integration/wide_compatibility.md#QUANTITY_SPEC)
is provided and used consistently through the library to allow the code to compile with C++20
compilers, thanks to the CRTP usage under the hood.
docs/users_guide/index.md
+9 -17
View File
@@ -48,30 +48,22 @@ Core concepts that form the foundation of **mp-units**:
- [Text Output](framework_basics/text_output.md) - Formatting and printing quantities
<!-- markdownlint-enable MD013 -->
### Systems
### [Systems](systems/index.md)
Available unit systems and their specifics:
- [Introduction](systems/index.md) - Overview of supported systems
- [International System of Quantities (ISQ)](systems/isq.md) - Standard quantity system
- [International System of Units (SI)](systems/si.md) - Metric system
- [IAU Astronomical Units](systems/iau.md) - Astronomical measurements
- [Centimetre-Gram-Second (CGS) System](systems/cgs.md) - CGS units
- [Yard-Pound Systems](systems/yard_pound.md) - Imperial and US customary units
- [Strong Angular System](systems/strong_angular_system.md) - Type-safe angle handling
- [Natural Units](systems/natural_units.md) - Units for particle physics
Detailed documentation of available unit systems (SI, CGS, Imperial, astronomical units,
natural units, etc.) with guidance on choosing the right one for your application domain.
## How to Use This Guide?
**Sequential Reading**: Start with [Terms and Definitions](terms_and_definitions.md) and
progress through [Framework Basics](#framework-basics) to build a complete mental model
of the library.
progress through the Framework Basics chapters to build a complete mental model of the
library.
**Reference Reading**: Jump to specific chapters when you need to understand a particular
concept in depth.
**Reference Reading**: Jump directly to specific chapters when you need to understand a
particular concept in depth.
**Combined Approach**: Read [Framework Basics](#framework-basics) sequentially for core
concepts, then refer to [Systems](#systems) chapters as needed for your specific domain.
**Domain-Focused**: After covering Framework Basics, explore the [Systems](systems/index.md)
chapter most relevant to your application domain.
## When to Use the User's Guide?
docs/workshops/extracting_numeric_values.md
+1 -1
View File
@@ -160,7 +160,7 @@ int main()
## References
- [User's Guide: Working with Legacy Interfaces](../how_to_guides/working_with_legacy_interfaces.md)
- [User's Guide: Working with Legacy Interfaces](../how_to_guides/integration/working_with_legacy_interfaces.md)
- [API Reference](../reference/api_reference.md)
docs/workshops/incremental_migration.md
+3 -3
View File
@@ -10,7 +10,7 @@ transition.
You'll learn the **bridge pattern**: specialize `quantity_like_traits` to enable seamless
conversion between legacy types and **mp-units**, then **add new features** using mp-units
while keeping existing code working unchanged. For complete details on `quantity_like_traits`,
see the [Interoperability with Other Libraries](../how_to_guides/interoperability_with_other_libraries.md)
see the [Interoperability with Other Libraries](../how_to_guides/integration/interoperability_with_other_libraries.md)
guide.
**Key migration strategy**: This workshop demonstrates an asymmetric approach to interoperability.
@@ -478,9 +478,9 @@ int main()
## References
<!-- markdownlint-disable MD013 -->
- [Interoperability with Other Libraries](../how_to_guides/interoperability_with_other_libraries.md) -
- [Interoperability with Other Libraries](../how_to_guides/integration/interoperability_with_other_libraries.md) -
Complete guide to `quantity_like_traits`
- [Working with Legacy Interfaces](../how_to_guides/working_with_legacy_interfaces.md) -
- [Working with Legacy Interfaces](../how_to_guides/integration/working_with_legacy_interfaces.md) -
Extracting numerical values and working with `double`-based APIs
<!-- markdownlint-enable MD013 -->
docs/workshops/interop_with_std_chrono.md
+1 -1
View File
@@ -209,7 +209,7 @@ int main()
## References
- [User's Guide: Interoperability with Other Libraries](../how_to_guides/interoperability_with_other_libraries.md)
- [User's Guide: Interoperability with Other Libraries](../how_to_guides/integration/interoperability_with_other_libraries.md)
- [API Reference](../reference/api_reference.md)
mkdocs.yml
+9 -5
View File
@@ -213,11 +213,15 @@ nav:
- "Workshop 14: Incremental Migration": workshops/incremental_migration.md
- How-to Guides:
- How-to Guides: how_to_guides/index.md
- Pure Dimensional Analysis: how_to_guides/pure_dimensional_analysis.md
- Working with Legacy Interfaces: how_to_guides/working_with_legacy_interfaces.md
- Using Custom Representation Types: how_to_guides/using_custom_representation_types.md
- Interoperability with Other Libraries: how_to_guides/interoperability_with_other_libraries.md
- Wide Compatibility: how_to_guides/wide_compatibility.md
- Advanced Usage:
- Overview: how_to_guides/advanced_usage/index.md
- Pure Dimensional Analysis: how_to_guides/advanced_usage/pure_dimensional_analysis.md
- Integration:
- Overview: how_to_guides/integration/index.md
- Working with Legacy Interfaces: how_to_guides/integration/working_with_legacy_interfaces.md
- Using Custom Representation Types: how_to_guides/integration/using_custom_representation_types.md
- Interoperability with Other Libraries: how_to_guides/integration/interoperability_with_other_libraries.md
- Wide Compatibility: how_to_guides/integration/wide_compatibility.md
- Examples:
- Examples: examples/index.md
- Tags: examples/tags.md