build2 integration doc update

Signed-off-by: Joël Lamotte <mjklaim@gmail.com>
Signed-off-by: Klaim (Joël Lamotte) <142265+Klaim@users.noreply.github.com>

docs/mkdocs/docs/integration/build2/example.cpp

@@ -0,0 +1,10 @@
+#include <nlohmann/json.hpp>
+#include <iostream>
+#include <iomanip>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::setw(4) << json::meta() << std::endl;
+}

docs/mkdocs/docs/integration/package_managers.md

@@ -477,8 +477,8 @@ dotnet add package nlohmann.json
     recommends adding “native” and “nativepackage” tags to C++ NuGet packages to distinguish them, but even adding
     “native” to search query would still show many .NET-only packages in the list.
 
-    Nevertheless, after finding the package you want, click on “Install” button and accept confirmation dialogs.
-    After the package is successfully added to the projects, you should be able to build and execute the project
+    Nevertheless, after finding the package you want, just click on “Install” button and accept confirmation dialogs.
+    After the package is successfully added to the projects, you should be able to just build and execute the project
     without the need for making any more changes to build settings.
 
     !!! note
@@ -700,13 +700,73 @@ to install the [nlohmann-json](https://ports.macports.org/port/nlohmann-json/) p
 
 ## build2
 
-If you are using [`build2`](https://build2.org), you can use the [`nlohmann-json`](https://cppget.org/nlohmann-json)
-package from the public repository <http://cppget.org> or directly from the
-[package's sources repository](https://github.com/build2-packaging/nlohmann-json). In your project's `manifest` file,
-add `depends: nlohmann-json` (probably with some [version constraints](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-add-remove-deps)). If you are not familiar with using dependencies in `build2`, [please read this introduction](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml).
-Please file issues [here](https://github.com/build2-packaging/nlohmann-json) if you experience problems with the packages.
+!!! abstract "Summary"
 
-:material-update: The [package](https://cppget.org/nlohmann-json) is updated automatically.
+    package: **`nlohmann-json`**
+    library target: **`nlohmann-json%`**
+    available in package repositories:
+      - [`cppget.org` (recommended)](https://cppget.org/nlohmann-json)
+      - [package's sources (for advanced users)](https://github.com/build2-packaging/nlohmann-json/)
+
+    - :octicons-tag-24: Available versions: current version and older versions since `3.7.3` (see [cppget.org](https://cppget.org/nlohmann-json))
+    - :octicons-rocket-24: The package is maintained and published by the community in [this the repository][(https://github.com/conan-io/conan-center-index/tree/master/recipes/nlohmann_json](https://github.com/build2-packaging/nlohmann-json/)).
+    - :octicons-file-24: File issues at the [package source repository](https://github.com/build2-packaging/nlohmann-json/issues/)
+    - :octicons-question-24: [`build2` website](https://build2)
+
+To use this package in an exising [`build2`](https://build2.org) project, the general steps are:
+
+  0. <details><summary>Make the package available to download from a package repository that provides it.</b></summary>
+
+      Your project's `repositories.manifest` specifies where the package manager will try to acquire packages by default. Make sure one of the repositories specified in this file provides `nlhomann-json` package.
+      The recommended open-source repository is [`cppget.org`](https://cppget.org/).
+
+      If the project has been created using [`bdep new`](https://build2.org/bdep/doc/bdep-new.xhtml), `cppget.org` is already specified in `repositories.manifest` but commented, just uncomment these lines:
+      ```
+      :
+      role: prerequisite
+      location: https://pkg.cppget.org/1/stable
+      ```
+      </details>
+
+  1. <details><summary>Add this package as dependency of your project.</summary>
+
+       In your project's `manifest` add the dependency to the package, like `depends: nlohmann-json`, probably with some [version constraints](https://build2.org/build2-toolchain/doc/build2-toolchain-intro.xhtml#guide-add-remove-deps).
+       For example, to depend on the latest `3.x` version available:
+       ```
+       depends: nlohmann-json ^3.0.0
+       ```
+       </details>
+
+
+  2. <details><summary>Add this library (from the package) as dependency of your target that uses it.</summary>
+
+      In the `buildfile` defining the target that will use this library:
+        - import the target from the `nlhomann-json` package, for example:
+           ```
+           import nljson = nlhomann-json%json
+           ```
+        - add the library's target as requirement for your target using it, for example:
+           ```
+           exe{example} : ... $nljson
+           ```
+      </details>
+
+  3. <details><summary>Use the library in your project's code and build it.</summary>
+
+      At this point, any `b` or `bdep update` command that will update/build the project will also acquire the missing dependency automatically, then build it and link it with your target.
+
+      If you just want to trigger the dependencies synchronization for all your configurations:
+        ```
+        bdep sync -af
+        ```
+      </details>
+
+??? example "Example: from scratch, using `build2`'s [`bdep new` command](https://build2.org/bdep/doc/bdep-new.xhtml)"
+```
+# create a simple executable project from scratch, with a simplfied directory layout, using `.hpp/.cpp` file extensions:
+bdep new example -exe,no-subdirs,no-tests -l c++,cpp
+
+```
 
 ```shell
 bdep new -t exe -l c++