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_sax/binary.md

@@ -0,0 +1,24 @@
+# <small>nlohmann::json_sax::</small>binary
+
+```cpp
+virtual bool binary(binary_t& val) = 0;
+```
+
+A binary value was read.
+
+## Parameters
+
+`val` (in)
+:   binary value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Notes
+
+It is safe to move the passed binary value.
+
+## Version history
+
+- Added in version 3.8.0.

doc/mkdocs/docs/api/json_sax/boolean.md

@@ -0,0 +1,20 @@
+# <small>nlohmann::json_sax::</small>boolean
+
+```cpp
+virtual bool boolean(bool val) = 0;
+```
+
+A boolean value was read.
+
+## Parameters
+
+`val` (in)
+:   boolean value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/end_array.md

@@ -0,0 +1,15 @@
+# <small>nlohmann::json_sax::</small>end_array
+
+```cpp
+virtual bool end_array() = 0;
+```
+
+The end of an array was read.
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/end_object.md

@@ -0,0 +1,15 @@
+# <small>nlohmann::json_sax::</small>end_object
+
+```cpp
+virtual bool end_object() = 0;
+```
+
+The end of an object was read.
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

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

@@ -0,0 +1,44 @@
+# <small>nlohmann::</small>json_sax
+
+```cpp
+template<typename BasicJsonType>
+struct json_sax;
+```
+
+This class describes the SAX interface used by [sax_parse](../basic_json/sax_parse.md). Each function is called in
+different situations while the input is parsed. The boolean return value informs the parser whether to continue
+processing the input.
+
+## Template parameters
+
+`BasicJsonType`
+:   a specialization of [`basic_json`](../basic_json/index.md)
+
+## Member types
+
+- [**number_integer_t**](../basic_json/number_integer_t.md) - `BasicJsonType`'s type for numbers (integer)
+- [**number_unsigned_t**](../basic_json/number_unsigned_t.md) - `BasicJsonType`'s  type for numbers (unsigned)
+- [**number_float_t**](../basic_json/number_float_t.md) - `BasicJsonType`'s type for numbers (floating-point)
+- [**string_t**](../basic_json/string_t.md) - `BasicJsonType`'s type for strings
+- [**binary_t**](../basic_json/binary_t.md) - `BasicJsonType`'s type for binary arrays
+
+## Member functions
+
+- [**binary**](binary.md) (_virtual_) - a binary value was read
+- [**boolean**](boolean.md) (_virtual_) - a boolean value was read
+- [**end_array**](end_array.md) (_virtual_) - the end of an array was read
+- [**end_object**](end_object.md) (_virtual_) - the end of an object was read
+- [**key**](key.md) (_virtual_) - an object key was read
+- [**null**](null.md) (_virtual_) - a null value was read
+- [**number_float**](number_float.md) (_virtual_) - a floating-point number was read
+- [**number_integer**](number_integer.md) (_virtual_) - an integer number was read
+- [**number_unsigned**](number_unsigned.md) (_virtual_) - an unsigned integer number was read
+- [**parse_error**](parse_error.md) (_virtual_) - a parse error occurred
+- [**start_array**](start_array.md) (_virtual_) - the beginning of an array was read
+- [**start_object**](start_object.md) (_virtual_) - the beginning of an object was read
+- [**string**](string.md) (_virtual_) - a string value was read
+
+## Version history
+
+- Added in version 3.2.0.
+- Support for binary values (`binary_t`, `binary`) added in version 3.8.0.

doc/mkdocs/docs/api/json_sax/key.md

@@ -0,0 +1,24 @@
+# <small>nlohmann::json_sax::</small>key
+
+```cpp
+virtual bool key(string_t& val) = 0;
+```
+
+An object key was read.
+
+## Parameters
+
+`val` (in)
+:   object key
+
+## Return value
+
+Whether parsing should proceed.
+
+## Notes
+
+It is safe to move the passed object key value.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/null.md

@@ -0,0 +1,15 @@
+# <small>nlohmann::json_sax::</small>null
+
+```cpp
+virtual bool null() = 0;
+```
+
+A null value was read.
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/number_float.md

@@ -0,0 +1,23 @@
+# <small>nlohmann::json_sax::</small>number_float
+
+```cpp
+virtual bool number_float(number_float_t val, const string_t& s) = 0;
+```
+
+A floating-point number was read.
+
+## Parameters
+
+`val` (in)
+:   floating-point value
+
+`s` (in)
+:   string representation of the original input
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/number_integer.md

@@ -0,0 +1,20 @@
+# <small>nlohmann::json_sax::</small>number_integer
+
+```cpp
+virtual bool number_integer(number_integer_t val) = 0;
+```
+
+An integer number was read.
+
+## Parameters
+
+`val` (in)
+:   integer value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/number_unsigned.md

@@ -0,0 +1,20 @@
+# <small>nlohmann::json_sax::</small>number_unsigned
+
+```cpp
+virtual bool number_unsigned(number_unsigned_t val) = 0;
+```
+
+An unsigned integer number was read.
+
+## Parameters
+
+`val` (in)
+:   unsigned integer value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/parse_error.md

@@ -0,0 +1,28 @@
+# <small>nlohmann::json_sax::</small>parse_error
+
+```cpp
+virtual bool parse_error(std::size_t position,
+                         const std::string& last_token,
+                         const detail::exception& ex) = 0;
+```
+
+A parse error occurred.
+
+## Parameters
+
+`position` (in)
+:   the position in the input where the error occurs
+
+`last_token` (in)
+:   the last read token
+
+`ex` (in)
+:   an exception object describing the error
+
+## Return value
+
+Whether parsing should proceed (**must return `#!cpp false`**).
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/start_array.md

@@ -0,0 +1,24 @@
+# <small>nlohmann::json_sax::</small>start_array
+
+```cpp
+virtual bool start_array(std::size_t elements) = 0;
+```
+
+The beginning of an array was read.
+
+## Parameters
+
+`elements` (in)
+:   number of object elements or `#!cpp -1` if unknown
+
+## Return value
+
+Whether parsing should proceed.
+
+## Notes
+
+Binary formats may report the number of elements.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/start_object.md

@@ -0,0 +1,24 @@
+# <small>nlohmann::json_sax::</small>start_object
+
+```cpp
+virtual bool start_object(std::size_t elements) = 0;
+```
+
+The beginning of an object was read.
+
+## Parameters
+
+`elements` (in)
+:   number of object elements or `#!cpp -1` if unknown
+
+## Return value
+
+Whether parsing should proceed.
+
+## Notes
+
+Binary formats may report the number of elements.
+
+## Version history
+
+- Added in version 3.2.0.

doc/mkdocs/docs/api/json_sax/string.md

@@ -0,0 +1,24 @@
+# <small>nlohmann::json_sax::</small>string
+
+```cpp
+virtual bool string(string_t& val) = 0;
+```
+
+A string value was read.
+
+## Parameters
+
+`val` (in)
+:   string value
+
+## Return value
+
+Whether parsing should proceed.
+
+## Notes
+
+It is safe to move the passed string value.
+
+## Version history
+
+- Added in version 3.2.0.