docs: Rework of "Getting Started" section

Inspired by #603

CONTRIBUTING.md

@@ -1,93 +1,220 @@
-# Contributing to `mp-units`
+# Contributing
 
 👍🎉 First off, thanks for taking the time to contribute! 🎉👍
 
+
+## Where To Start?
+
+If you are looking for a good issue to start with, please check the following:
+
+- [good first issue](https://github.com/mpusz/mp-units/labels/good%20first%20issue) - issues that
+ should be pretty simple to implement,
+- [help wanted](https://github.com/mpusz/mp-units/labels/help%20wanted) - issues that typically are
+ a bit more involved than beginner issues,
+- [high priority](https://github.com/mpusz/mp-units/labels/high%20priority) - things to fix ASAP
+ but often of higher complexity.
+
+
 ## Gitpod
 
-The easiest way to start coding is to jump straight into [Gitpod](https://www.gitpod.io). You can either click the button
-below or prefix any `mp-units` URL (main branch, other branches, issues, PRs, ...) in your web browser with `gitpod.io/#`
-(e.g., <https://gitpod.io/#https://github.com/mpusz/mp-units>).
+The easiest way to start coding is to jump straight into [Gitpod](https://www.gitpod.io)
+environment. You can either click the button below
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mpusz/mp-units)
 
+or prefix any `mp-units` URL (main branch, other branches, issues, PRs, ...) in your web browser
+with `gitpod.io/#` (e.g., <https://gitpod.io/#https://github.com/mpusz/mp-units>).
+
 The above environment provides you with:
 
-- all supported compilers for Linux development and the latest version of build tools like `cmake` and `conan`
-- all Conan dependencies preinstalled on the machine
-- all documentation generation tools ready to use
-- completed prebuilds for all targets (Debug and Release builds for each compiler)
-- VSCode preconfigured to benefit from all the above
+- all supported compilers for Linux development and the latest version of build tools like `cmake`
+  and `conan`,
+- all Conan dependencies preinstalled on the machine,
+- all documentation generation tools ready to use,
+- completed prebuilds for all targets (Debug and Release builds for each compiler),
+- VSCode preconfigured to benefit from all the above.
 
-## Download, Build, Install
+
+## Building, testing, and packaging
 
 Alternatively, please refer to our official docs for
-[download, build, and install instructions](https://mpusz.github.io/mp-units/latest/getting_started/installation_and_usage)
-if you want to setup a development environment on your local machine.
+[download, build, and install instructions](https://mpusz.github.io/mp-units/latest/getting_started/installation_and_usage) with the below changes
+if you want to set up a development environment on your local machine.
 
-## Before Committing git Changes
 
-There are a few steps recommended to check before committing and pushing your changes to the git repository.
+### Conan configuration properties
 
-### Naming Conventions
+[`user.mp-units.build:all`](#user.mp-units.build-all){ #user.mp-units.build-all }
 
-Here are the main rules for naming things in this repo:
+ Enables compilation of all the source code, including tests and examples. To support this, it requires some additional Conan build dependencies described in
+ [Repository directory tree and dependencies](https://mpusz.github.io/mp-units/latest/getting_started/project_structure#cmake-projects-and-dependencies).
+ It also runs unit tests during the Conan build (unless
+ [`tools.build:skip_test`](https://docs.conan.io/2/reference/commands/config.html?highlight=tools.build:skip_test#conan-config-list)
+ configuration property is set to `True`).
 
-- types, functions, variables naming in a `standard_case`
-- template parameters in a `PascalCase`
-- C++20 concepts names for now in a `PascalCase` but we plan to change it (see <https://github.com/mpusz/mp-units/issues/93>
-  for more details)
+ [conan build all support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
 
-### Unified Code Formatting
+[`user.mp-units.build:skip_la`](#user-skip-la){ #user-skip-la }
 
-There is a formatting standard enforced with the `pre-commit` script. Before committing your changes please do the following:
+ If `user.mp-units.build:all` is enabled, among others, Conan installs the external
+ [wg21-linear_algebra](https://conan.io/center/recipes/wg21-linear_algebra)
+ dependency and enables the compilation of linear algebra-based tests and usage examples.
+ Such behavior can be disabled with this option.
 
-```bash
-pip3 install -U pre-commit
-pre-commit run --all-files
+ [conan skip la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+
+[`user.mp-units.analyze:clang-tidy`](#user.mp-units.analyze-clang-tidy){ #user.mp-units.analyze-clang-tidy }
+
+ Enables clang-tidy analysis.
+
+ [conan clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+
+
+### CMake options for mp-units project developers
+
+[`MP_UNITS_DEV_BUILD_LA`](#MP_UNITS_DEV_BUILD_LA){ #MP_UNITS_DEV_BUILD_LA }
+
+:   [:octicons-tag-24: 2.2.0][cmake build la support] · :octicons-milestone-24: `ON`/`OFF` (Default: `ON`)
+
+ Enables building code depending on the linear algebra library.
+
+ [cmake build la support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+
+[`MP_UNITS_DEV_IWYU`](#MP_UNITS_DEV_IWYU){ #MP_UNITS_DEV_IWYU }
+
+:   [:octicons-tag-24: 2.2.0][cmake iwyu support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
+
+ Enables include-what-you-use analysis.
+
+ [cmake iwyu support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+
+[`MP_UNITS_DEV_CLANG_TIDY`](#MP_UNITS_DEV_CLANG_TIDY){ #MP_UNITS_DEV_CLANG_TIDY }
+
+:   [:octicons-tag-24: 2.2.0][cmake clang-tidy support] · :octicons-milestone-24: `ON`/`OFF` (Default: `OFF`)
+
+ Enables clang-tidy analysis.
+
+ [cmake clang-tidy support]: https://github.com/mpusz/mp-units/releases/tag/v2.2.0
+
+
+### Building the entire repository
+
+To build all the **mp-units** source code (with unit tests and examples), you should:
+
+1. Use the _CMakeLists.txt_ from the top-level directory.
+2. Run Conan with [`user.mp-units.build:all`](#user.mp-units.build-all) = `True`.
+
+```shell
+git clone https://github.com/mpusz/mp-units.git && cd units
+conan build . -pr <your_conan_profile> -s compiler.cppstd=23 -o '&:cxx_modules=True' -c user.mp-units.build:all=True -b missing
 ```
 
-This will run `clang-format` for code formatting with the `.clang-format` file provided in the repo, `cmake-format` to format
-the CMake files, and some other check as well.
-The script will run on all the files in the repo and will apply the changes in-place when needed.
-After the script is done please make sure to stage all those changes to git commit.
+The above will download and install all of the dependencies needed for the development of the library,
+build all of the source code, and run unit tests.
 
-### Build All CMake Targets And Run Unit Tests
+If you prefer to build the project via CMake rather than Conan, then you should replace
+the `conan build` with `conan install` command and then follow with a regular CMake build and testing:
 
-The simplest way to verify if all targets build correctly and all unit tests pass is to run:
+```shell
+conan install . -pr <your_conan_profile> -s compiler.cppstd=23 -o '&:cxx_modules=True' -c user.mp-units.build:all=True -b missing
+cmake --preset conan-default
+cmake --build --preset conan-release
+cmake --build --preset conan-release --target all_verify_interface_header_sets
+cmake --build --preset conan-release --target test
+```
 
-```bash
-conan build . -pr <your_conan_profile> -s compiler.cppstd=23 -o cxx_modules=True -c user.mp-units.build:all=True -b missing
+!!! hint
+
+    To ensure that we always build all the targets and to save some typing of the Conan commands,
+    we can set the following in the `~/.conan2/global.conf`:
+
+    ```text
+    user.mp-units.build:all=True
+    ```
+
+### Packaging
+
+To test CMake installation and Conan packaging run:
+
+```shell
+conan create . --user <username> --channel <channel> -pr <your_conan_profile> -s compiler.cppstd=20 -o '&:cxx_modules=True' -c user.mp-units.build:all=True -b missing
 ```
 
-as described in the
-[Installation and Usage](https://mpusz.github.io/mp-units/latest/getting_started/installation_and_usage/#contributing-or-just-building-all-the-tests-and-examples)
-chapter of our documentation.
+The above will create a Conan package and run tests provided in _./test_package_ directory.
 
-_Hint:_ To ensure that that we always build all the targets and to save some typing of the Conan commands,
-it is a good practice to set the following in the `~/.conan2/global.conf`:
+In case you would like to upload **mp-units** package to the Conan server do the following:
 
-```text
-user.mp-units.build:all=True
+```shell
+conan upload -r <remote-name> --all mp-units/2.2.0@<user>/<channel>
 ```
 
-Non-Conan users should:
-- build `all` and `all_verify_interface_header_sets` CMake targets,
-- run all unit tests.
 
-### Backward Compatibility
+## Building documentation
 
-Before submission, please remember to check if the code compiles fine on the supported compilers.
-The CI will check it anyway but it is good to check at least some of the configurations before pushing changes.
-Especially older compilers can be tricky as those do not support all the C++20 features well enough. The official
-list of supported compilers can be always found in the
-[Installation And Usage](https://mpusz.github.io/mp-units/latest/getting_started/cpp_compiler_support)
-chapter of our documentation.
+We are building our documentation using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). The easiest way to install all the required dependencies is with `pip`:
 
+```shell
+pip install -U mkdocs-material mkdocs-rss-plugin
+```
 
-## Where To Start?
+Additionally, a [Cairo Graphics library](https://www.cairographics.org/) is required by
+Material for MkDocs. Please follow the
+[official MkDocs documentation to install it](https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#cairo-graphics).
+
+After that, you can either:
+
+- easily [start a live server to preview the documentation as you write](https://squidfunk.github.io/mkdocs-material/creating-your-site/#previewing-as-you-write)
+
+```shell
+mkdocs serve
+```
+
+- [build the documentation](https://squidfunk.github.io/mkdocs-material/creating-your-site/#building-your-site)
+
+```shell
+mkdocs build
+```
+
+
+## Before Committing git Changes
+
+There are a few steps recommended to check before committing and pushing your changes to the git
+repository.
 
-If you are looking for a good issue to start with, please check the following:
 
-- [good first issue](https://github.com/mpusz/mp-units/labels/good%20first%20issue) - issues that should be pretty simple to implement.
-- [help wanted](https://github.com/mpusz/mp-units/labels/help%20wanted) - issues that typically are a bit more involved than beginner issues.
-- [high priority](https://github.com/mpusz/mp-units/labels/high%20priority) - things to fix ASAP but often of higher complexity.
+### Naming Conventions
+
+Here are the main rules for naming things in this repo:
+
+- types, functions, variables use `standard_case`,
+- template parameters use `PascalCase`,
+- C++ concept names, for now, use `PascalCase`, but we plan to change it
+ (see [GitHub Issue #93](https://github.com/mpusz/mp-units/issues/93) for more details).
+
+### Unified Code Formatting
+
+A formatting standard is enforced with the `pre-commit` script. Before committing your changes, please do the following:
+
+```bash
+pip install -U pre-commit
+pre-commit run --all-files
+```
+
+This will run:
+
+- `clang-format` for code formatting with the `.clang-format` file provided in the repo,
+- `cmake-format` to format the CMake files,
+- some other checks (e.g., python script checkers, whitespaces, etc.).
+
+The script will run on all the files in the repo and will apply the changes in place when needed.
+After the script is done, please make sure to review and stage all those changes for the git commit.
+
+
+### Backward Compatibility
+
+Before submission, please remember to check if the code compiles fine on the supported compilers.
+The CI will check it anyway, but it is good to check at least some of the configurations before
+pushing changes.
+Especially older compilers can be tricky as those do not have full C++20 conformance.
+The official list of supported compilers can be always found in the
+[C++ compiler support (API/ABI)](https://mpusz.github.io/mp-units/latest/getting_started/cpp_compiler_support) chapter of our documentation.

docs/getting_started/contributing.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md