diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 07318c6c..f50c95fe 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -48,7 +48,7 @@ static_assert(10q_km / 5q_km == 2); The most important concepts in the library are `Unit`, `Dimension`, and `Quantity`: -![Design UML](design.png) +![Design UML](_static/img/concepts.png) `Unit` is a basic building block of the library. Every dimension works with a concrete hierarchy of units. Such hierarchy defines a reference unit and often a few scaled versions of @@ -86,7 +86,7 @@ and `Ratio` is satisfied by any instantiation of `units::ratio`. The `scaled_unit` type is a framework's private type and the user should never instantiate it directly. The public user interface to create units consists of: -![Units UML](units.png) +![Units UML](_static/img/units.png) All below class templates indirectly derive from a `scaled_unit` class template and satisfy a `Unit` concept: @@ -620,7 +620,7 @@ User-friendly, short name printed by the compiler and the debugger. To fix it we have to provide a strong type. As we do not have opaque/strong typedefs in the language we have to use inheritance: -![UML](downcast_1.png) +![UML](_static/img/downcast_1.png) This gives us a nice looking strong type but does not solve the problem of how to switch from a long instantiation of a `derived_dimension_base` class template that was generated by the @@ -636,7 +636,7 @@ specific base class template instantiation. Downcasting facility is provided by injecting two classes into our hierarchy: -![UML](downcast_2.png) +![UML](_static/img/downcast_2.png) In the above example `dim_area` is a downcasting target (child class) and a specific `detail::derived_dimension` class template instantiation is a downcasting source (base class). diff --git a/docs/INSTALL.md b/docs/INSTALL.md deleted file mode 100644 index 658c72ce..00000000 --- a/docs/INSTALL.md +++ /dev/null @@ -1,157 +0,0 @@ -# Installation Guide - -## Repository structure - -This repository contains three independent `cmake`-based projects: -1. `./src` - - header-only project containing whole `mp-units` library -2. `.` - - project used as an entry point for library development (it wraps `./src` project - together with usage examples and tests) - -3. `./test_package` - library installation and Conan package verification - -NOTE: Please note that this repository depends on a git submodule in the `./cmake/common` -subdirectory. - - -## Installation and Reuse - -There are a few different ways of installing/reusing `units` in your project. - -### Conan quick intro - -In case you are not familiar with `conan`, to install it just do: - -```shell -pip3 install -U conan -``` - -After that you might need to add a custom profile in `~/.conan/profile` for your -developnment environment. An example profile can look as follows: - -```text -[settings] -os=Linux -os_build=Linux -arch=x86_64 -arch_build=x86_64 -compiler=gcc -compiler.version=9 -compiler.cppstd=20 -compiler.libcxx=libstdc++11 -build_type=Release - -[options] -[build_requires] - -[env] -CC=/usr/bin/gcc-9 -CXX=/usr/bin/g++-9 -``` - -### Copy - -As `units` is a header-only library you can simply copy `src/include` directory to -your source tree and use it as regular header files. - -NOTE: Until C++20 arrives the library has some 3rd party dependencies that provide -experimental C++20 features. The list of dependencies include: -- `range-v3@ericniebler` (only for gcc-9, gcc-10 uses gcc's concepts implementation) -- `fmt@_` - -All of them are easily to obtain with `conan`. - -NOTE: In case a full library's repository is to be compiled (instead of just copying -`src/include` headers), additionally, the library's unit tests depend on -`Catch2@catchorg` and `linear_algebra@public-conan` conan packages. - -### cmake + conan - -To use `units` as a `cmake` imported library via `cmake` configuration files the following -steps may be done: -- clone the repository with its submodules: - - ```shell - git clone --recurse-submodules https://github.com/mpusz/units.git - ``` - - or in case it is already cloned without submodules initialize, fetch, and checkout them with: - - ```shell - git submodule update --init - ``` - -- add the following remotes to your local `conan` instance - - ```shell - conan remote add conan-mpusz https://api.bintray.com/conan/mpusz/conan-mpusz - ``` - -- add `units` as a dependency to your `conan` file. For example to use testing version of - `0.5.0` of `mp-units` add: - - `conanfile.txt` - - ```ini - [requires] - mp-units/0.5.0@mpusz/testing - ``` - - - `conanfile.py` - - ```python - requires = "mp-units/0.5.0@mpusz/testing" - ``` - -- import `conan` dependencies to top level `CMakeLists.txt` file - - ```cmake - include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) - conan_basic_setup(TARGETS) - ``` - -- link your `cmake` target with units - - ```cmake - target_link_libraries( PUBLIC|PRIVATE|INTERFACE CONAN_PKG::mp-units) - ``` - -- install `conan` dependencies before configuring cmake - - ```shell - cd build - conan install .. -pr -s compiler.cppstd=20 -b=outdated -u - ``` - - -## Full build and unit testing - -In case you would like to build all the code in this repository (with unit tests and examples) -you should use the `CMakeLists.txt` from the parent directory and run Conan with -`CONAN_RUN_TESTS=True`. - -```shell -git clone --recurse-submodules https://github.com/mpusz/units.git -mkdir units/build && cd units/build -conan remote add linear_algebra https://api.bintray.com/conan/twonington/public-conan -conan install .. -pr -s compiler.cppstd=20 -e CONAN_RUN_TESTS=True -b outdated -cmake .. -DCMAKE_BUILD_TYPE=Release -cmake --build . -ctest -VV -``` - - -## Packaging - -To create a `conan` package and test `cmake` installation and `conan` packaging run: - -```shell -conan create . / -pr -s compiler.cppstd=20 -e CONAN_RUN_TESTS=True -b outdated -``` - - -## Upload package to conan server - -```shell -conan upload -r --all mp-units/0.5.0@/ -``` diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 96e41697..00000000 --- a/docs/README.md +++ /dev/null @@ -1,115 +0,0 @@ -# `mp-units` - Documentation - -## How to build? - -1. Install the requirements (Sphinx) with: - - ```shell - pip3 install -r docs/requirements.txt - ``` - -2. Install all dependencies with Conan for a developer's build: - - ```shell - conan install .. -pr -s compiler.cppstd=20 -e CONAN_RUN_TESTS=True -b outdated - ``` - -3. Install Python 3 -4. Build the documentation with a regular CMake build - - -## How to contribute? - -To make any contribution to **mp-units** documentation please fork this repository and open -a Pull Request. - -### Style Guidelines - -This guidelines are just general good practices for the formatting and structure of the whole -documentation and do not pretend to be a stopper for any helpful contribution. Any contribution -that may include relevant information for **mp-units** users will always be welcomed. - -**mp-units** documentation is written in [reStructuredText](http://docutils.sourceforge.net/rst.html) -and follows [reStructuredText Markup Specification](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html). - -[Quick reStructuredText](http://docutils.sourceforge.net/docs/user/rst/quickref.html) is also -used for reference. - -Any detail not covered by this guidelines will follow the aforementioned rules. - -#### Section titles - -Use section titles in this level of importance: - -```rst -Section Title -============= - -Subsection Title ----------------- - -Subsubsection Title -^^^^^^^^^^^^^^^^^^^ -``` - -#### Text emphasis/highlighting - -- **Bold text** to highlight important text: - - ```rst - **mp-units** is a compile-time enabled Modern C++ library that provides compile-time dimensional - analysis and unit/quantity manipulation. - ``` - -- *Italics* to refer to file names, directory names, and paths. - - ```rst - Create Conan configuration file (either *conanfile.txt* or *conanfile.py*) in your project's - top-level directory... - ``` - -- ``Inline literals`` to refer to the in examples that is not a part of the **mp-units** library: - - ```rst - Let's assume that the user wants to implement an ``avg_speed`` function that will - be calculating the average speed based on provided distance and duration quantities. - ``` - -#### Literal blocks - -Most of the C++ code examples should be provided as literal blocks after double `::` symbol: - -```rst -For this dimension-specific concepts come handy again and with usage of C++20 generic -functions our function can look as simple as:: - - constexpr Velocity auto avg_speed(Length auto d, Time auto t) - { - return d / t; - } -``` - -#### code-blocks - -Use code-blocks for exceptional cases like code samples in other languages or a need -to emphasize specific lines of code: - -```rst -Quantities of the same dimension can be easily added or subtracted with -each other and the result will always be a quantity of the same dimension: - -.. code-block:: - :emphasize-lines: 3-4 - - Length auto dist1 = 2q_m; - Length auto dist2 = 1q_m; - Length auto res1 = dist1 + dist2; - Length auto res2 = dist1 - dist2; -``` - -#### Indentation and line length - -Make sure all indentation is done with spaces. Normally 2 space indentation for bulleted lists -and 4 space indentation for code blocks and RST directives contents: - -Do not leave any unnecessary or trailing spaces. diff --git a/docs/_static/img/design.png b/docs/_static/img/concepts.png similarity index 100% rename from docs/_static/img/design.png rename to docs/_static/img/concepts.png diff --git a/docs/downcast_1.png b/docs/_static/img/downcast_1.png similarity index 100% rename from docs/downcast_1.png rename to docs/_static/img/downcast_1.png diff --git a/docs/downcast_2.png b/docs/_static/img/downcast_2.png similarity index 100% rename from docs/downcast_2.png rename to docs/_static/img/downcast_2.png diff --git a/docs/design.png b/docs/design.png deleted file mode 100644 index 256bbd4a..00000000 Binary files a/docs/design.png and /dev/null differ diff --git a/docs/design.rst b/docs/design.rst index 7f75264f..56eaedd3 100644 --- a/docs/design.rst +++ b/docs/design.rst @@ -11,3 +11,19 @@ Design :maxdepth: 2 design/quantity + +The Downcasting Facility +------------------------ + +.. + http://www.nomnoml.com + + [detail::derived_dimension_base>]<:-[dim_area] + + +.. + http://www.nomnoml.com + + [downcast_base>>]<:-[detail::derived_dimension_base>] + [detail::derived_dimension_base>]<:-[downcast_child>>] + [downcast_child>>]<:-[dim_area] diff --git a/docs/framework/basic_concepts.rst b/docs/framework/basic_concepts.rst index 178c7eae..e1f73cb4 100644 --- a/docs/framework/basic_concepts.rst +++ b/docs/framework/basic_concepts.rst @@ -6,7 +6,7 @@ Basic Concepts The most important concepts in the library are `Unit`, `Dimension`, and `Quantity`: -.. image:: /_static/img/design.png +.. image:: /_static/img/concepts.png :align: center .. diff --git a/docs/nomnoml.md b/docs/nomnoml.md deleted file mode 100644 index 878d4ac9..00000000 --- a/docs/nomnoml.md +++ /dev/null @@ -1,46 +0,0 @@ -# nomnoml - -Graphs in the documentation are created with . - -## Concepts - -```text -[Dimension| -[base_dimension]<-[exp] -[derived_dimension]<-[exp] -[exp]<-[derived_dimension] -] - -[Quantity| -[quantity] -] - -[Unit]<-[Dimension] -[Dimension]<-[Quantity] -[Unit]<-[Quantity] -``` - -## Units - -```text -#direction: right - -[scaled_unit]<:-[unit] -[scaled_unit]<:-[named_unit] -[scaled_unit]<:-[named_scaled_unit] -[scaled_unit]<:-[prefixed_unit] -[scaled_unit]<:-[deduced_unit] -``` - -## Downcasting 1 - -```text -[detail::derived_dimension_base>]<:-[dim_area] -``` - -## Downcasting 2 - -```text -[downcast_base>>]<:-[detail::derived_dimension_base>] -[detail::derived_dimension_base>]<:-[downcast_child>>] -[downcast_child>>]<:-[dim_area]``` \ No newline at end of file diff --git a/docs/units.png b/docs/units.png deleted file mode 100644 index 311abd6f..00000000 Binary files a/docs/units.png and /dev/null differ