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/examples/std_swap.cpp

@@ -0,0 +1,19 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create JSON values
+    json j1 = {{"one", 1}, {"two", 2}};
+    json j2 = {1, 2, 4, 8, 16};
+
+    std::cout << "j1 = " << j1 << " | j2 = " << j2 << '\n';
+
+    // swap values
+    std::swap(j1, j2);
+
+    std::cout << "j1 = " << j1 << " | j2 = " << j2 << std::endl;
+}