Consolidate documentation (#3071)

* 🔥 consolidate documentation
* ♻️ overwork std specializations
* 🚚 move images files to mkdocs
* ♻️ fix URLs
* 🔧 tweak MkDocs configuration
* 🔧 add namespaces
* 📝 document deprecations
* 📝 document documentation generation
* 🚸 improve search
* 🚸 add examples
* 🚧 start adding documentation for macros
* 📝 add note for https://github.com/nlohmann/json/issues/874#issuecomment-1001699139
* 📝 overwork example handling
* 📝 fix Markdown tables

doc/mkdocs/docs/api/json_pointer/back.md

@@ -0,0 +1,39 @@
+# <small>nlohmann::json_pointer::</small>back
+
+```cpp
+const std::string& back() const;
+```
+
+Return last reference token.
+
+## Return value
+
+Last reference token.
+
+## Exceptions
+
+Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example shows the usage of `back`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__back.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__back.output"
+    ```
+
+## Version history
+
+Added in version 3.6.0.

doc/mkdocs/docs/api/json_pointer/empty.md

@@ -0,0 +1,39 @@
+# <small>nlohmann::json_pointer::</small>empty
+
+```cpp
+bool empty() const noexcept;
+```
+
+Return whether pointer points to the root document.
+
+## Return value
+
+`#!cpp true` iff the JSON pointer points to the root document.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example shows the result of `empty` for different JSON Pointers.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__empty.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__empty.output"
+    ```
+
+## Version history
+
+Added in version 3.6.0.

doc/mkdocs/docs/api/json_pointer/index.md

@@ -0,0 +1,36 @@
+# <small>nlohmann::</small>json_pointer
+
+```cpp
+template<typename BasicJsonType>
+class json_pointer;
+```
+
+A JSON pointer defines a string syntax for identifying a specific value within a JSON document. It can be used with
+functions [`at`](../basic_json/at.md) and [`operator[]`](../basic_json/operator%5B%5D.md). Furthermore, JSON pointers
+are the base for JSON patches.
+
+## Template parameters
+
+`BasicJsonType`
+:   a specialization of [`basic_json`](../basic_json/index.md)
+
+## Member functions
+
+- [(constructor)](json_pointer.md)
+- [**to_string**](to_string.md) - return a string representation of the JSON pointer
+- [**operator std::string**](operator_string.md) - return a string representation of the JSON pointer
+- [**operator/=**](operator_slasheq.md) - append to the end of the JSON pointer
+- [**operator/**](operator_slash.md) - create JSON Pointer by appending
+- [**parent_pointer**](parent_pointer.md) - returns the parent of this JSON pointer
+- [**pop_back**](pop_back.md) - remove last reference token
+- [**back**](back.md) - return last reference token
+- [**push_back**](push_back.md) - append an unescaped token at the end of the pointer
+- [**empty**](empty.md) - return whether pointer points to the root document
+
+## See also
+
+- [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
+
+## Version history
+
+Added in version 2.0.0.

doc/mkdocs/docs/api/json_pointer/json_pointer.md

@@ -0,0 +1,40 @@
+# <small>nlohmann::json_pointer::</small>json_pointer
+
+```cpp
+explicit json_pointer(const std::string& s = "");
+```
+
+Create a JSON pointer according to the syntax described in
+[Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
+
+## Parameters
+
+`s` (in)
+:    string representing the JSON pointer; if omitted, the empty string is assumed which references the whole JSON value
+
+## Exceptions
+
+- Throws [parse_error.107](../../home/exceptions.md#jsonexceptionparse_error107) if the given JSON pointer `s` is 
+  nonempty and does not begin with a slash (`/`); see example below.
+- Throws [parse_error.108](../../home/exceptions.md#jsonexceptionparse_error108) if a tilde (`~`) in the given JSON
+  pointer `s` is not followed by `0` (representing `~`) or `1` (representing `/`); see example below.
+
+## Examples
+
+??? example
+
+    The example shows the construction several valid JSON pointers as well as the exceptional behavior.
+     
+    ```cpp
+    --8<-- "examples/json_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer.output"
+    ```
+
+## Version history
+
+Added in version 2.0.0.

doc/mkdocs/docs/api/json_pointer/operator_slash.md

@@ -0,0 +1,64 @@
+# <small>nlohmann::json_pointer::</small>operator/
+
+```cpp
+// (1)
+json_pointer operator/(const json_pointer& lhs, const json_pointer& rhs);
+
+// (2)
+json_pointer operator/(const json_pointer& lhs, std::string token);
+
+// (3)
+json_pointer operator/(const json_pointer& lhs, std::size_t array_idx);
+```
+
+1. create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
+2. create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
+3. create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
+
+## Parameters
+
+`lhs` (in)
+:    JSON pointer
+
+`rhs` (in)
+:    JSON pointer to append
+
+`token` (in)
+:    reference token to append
+
+`array_idx` (in)
+:    array index to append
+
+## Return value
+
+1. a new JSON pointer with `rhs` appended to `lhs`
+2. a new JSON pointer with unescaped `token` appended to `lhs`
+3. a new JSON pointer with `array_idx` appended to `lhs`
+
+## Complexity
+
+1. Linear in the length of `lhs` and `rhs`.
+2. Linear in the length of `lhs`.
+3. Linear in the length of `lhs`.
+
+## Examples
+
+??? example
+
+    The example shows the usage of `operator/`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__operator_add_binary.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__operator_add_binary.output"
+    ```
+
+## Version history
+
+1. Added in version 3.6.0.
+2. Added in version 3.6.0.
+3. Added in version 3.6.0.

doc/mkdocs/docs/api/json_pointer/operator_slasheq.md

@@ -0,0 +1,61 @@
+# <small>nlohmann::json_pointer::</small>operator/=
+
+```cpp
+// (1)
+json_pointer& operator/=(const json_pointer& ptr);
+
+// (2)
+json_pointer& operator/=(std::string token);
+
+// (3)
+json_pointer& operator/=(std::size_t array_idx)
+```
+
+1. append another JSON pointer at the end of this JSON pointer
+2. append an unescaped reference token at the end of this JSON pointer
+3. append an array index at the end of this JSON pointer
+
+## Parameters
+
+`ptr` (in)
+:    JSON pointer to append
+
+`token` (in)
+:    reference token to append
+
+`array_idx` (in)
+:    array index to append
+
+## Return value
+
+1. JSON pointer with `ptr` appended
+2. JSON pointer with `token` appended without escaping `token`
+3. JSON pointer with `array_idx` appended
+
+## Complexity
+
+1. Linear in the length of `ptr`.
+2. Amortized constant.
+3. Amortized constant.
+
+## Examples
+
+??? example
+
+    The example shows the usage of `operator/=`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__operator_add.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__operator_add.output"
+    ```
+
+## Version history
+
+1. Added in version 3.6.0.
+2. Added in version 3.6.0.
+3. Added in version 3.6.0.

doc/mkdocs/docs/api/json_pointer/operator_string.md

@@ -0,0 +1,24 @@
+# <small>nlohmann::json_pointer::</small>operator std::string
+
+```cpp
+operator std::string() const
+```
+
+Return a string representation of the JSON pointer.
+
+## Return value
+
+A string representation of the JSON pointer
+
+## Possible implementation
+
+```cpp
+operator std::string() const
+{
+    return to_string();
+}
+```
+
+## Version history
+
+Since version 2.0.0.

doc/mkdocs/docs/api/json_pointer/parent_pointer.md

@@ -0,0 +1,35 @@
+# <small>nlohmann::json_pointer::</small>parent_pointer
+
+```cpp
+json_pointer parent_pointer() const;
+```
+
+Returns the parent of this JSON pointer.
+
+## Return value
+
+Parent of this JSON pointer; in case this JSON pointer is the root, the root itself is returned.
+
+## Complexity
+
+Linear in the length of the JSON pointer.
+
+## Examples
+
+??? example
+
+    The example shows the result of `parent_pointer` for different JSON Pointers.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__parent_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__parent_pointer.output"
+    ```
+
+## Version history
+
+Added in version 3.6.0.

doc/mkdocs/docs/api/json_pointer/pop_back.md

@@ -0,0 +1,35 @@
+# <small>nlohmann::json_pointer::</small>pop_back
+
+```cpp
+void pop_back();
+```
+
+Remove last reference token.
+
+## Exceptions
+
+Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example shows the usage of `pop_back`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__pop_back.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__pop_back.output"
+    ```
+
+## Version history
+
+Added in version 3.6.0.

doc/mkdocs/docs/api/json_pointer/push_back.md

@@ -0,0 +1,38 @@
+# <small>nlohmann::json_pointer::</small>push_back
+
+```cpp
+void push_back(const std::string& token);
+
+void push_back(std::string&& token);
+```
+
+Append an unescaped token at the end of the reference pointer.
+
+## Parameters
+
+`token` (in)
+:   token to add
+
+## Complexity
+
+Amortized constant.
+
+## Examples
+
+??? example
+
+    The example shows the result of `push_back` for different JSON Pointers.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__push_back.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__push_back.output"
+    ```
+
+## Version history
+
+Added in version 3.6.0.

doc/mkdocs/docs/api/json_pointer/to_string.md

@@ -0,0 +1,39 @@
+# <small>nlohmann::json_pointer::</small>to_string
+
+```cpp
+std::string to_string() const;
+```
+
+Return a string representation of the JSON pointer.
+
+## Return value
+
+A string representation of the JSON pointer
+
+## Notes
+
+For each JSON pointer `ptr`, it holds:
+
+```cpp
+ptr == json_pointer(ptr.to_string());
+```
+
+## Examples
+
+??? example
+
+    The example shows the result of `to_string`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__to_string.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__to_string.output"
+    ```
+
+## Version history
+
+Since version 2.0.0.