Format-check the documentation examples in CI (#5386)

* Reformat parser_callback_t example with astyle

The file uses "json & /*parsed*/" in three lambda parameter lists, which
astyle rewrites to "json& /*parsed*/" per --align-reference=type. The
drift went unnoticed because CI never format-checked the documentation
examples; "make pretty" does cover them.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Format-check the documentation examples in CI

The examples live in docs/mkdocs/docs/examples, but both format checks
still referenced the long-gone docs/examples path:

- check_amalgamation.yml passed it to find, which printed an error for
  the missing path and carried on, so astyle only ever saw include and
  tests. The step still exited 0.
- ci.cmake globbed it into INDENT_FILES, and a GLOB_RECURSE over a
  missing directory silently yields nothing, so the ci_test_amalgamation
  target skipped the examples too.

Either way the 231 example files have never been format-checked. Point
both at the real path, and guard the workflow with an explicit directory
check so a future rename fails the job instead of quietly shrinking the
file list again.

Also drop the dead docs/examples/** path filter from
publish_documentation.yml; docs/mkdocs/** already covers the examples.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

Author: nlohmann

.github/workflows/check_amalgamation.yml

@@ -67,8 +67,18 @@ jobs:
           ${{ github.workspace }}/venv/bin/astyle --project=tools/astyle/.astylerc --suffix=none --quiet \
             $INCLUDE_DIR/json.hpp $INCLUDE_DIR/json_fwd.hpp
 
+          # fail loudly if a directory is renamed or removed: find would only warn
+          # about the missing path and silently drop its files from the check
+          SOURCE_DIRS="docs/mkdocs/docs/examples include tests"
+          for DIR in $SOURCE_DIRS; do
+            if [ ! -d "$DIR" ]; then
+              echo "::error::source directory '$DIR' does not exist"
+              exit 1
+            fi
+          done
+
           ${{ github.workspace }}/venv/bin/astyle --project=tools/astyle/.astylerc --suffix=none --quiet \
-            $(find docs/examples include tests -type f \( -name '*.hpp' -o -name '*.cpp' -o -name '*.cu' \) -not -path 'tests/thirdparty/*' -not -path 'tests/abi/include/nlohmann/*' | sort)
+            $(find $SOURCE_DIRS -type f \( -name '*.hpp' -o -name '*.cpp' -o -name '*.cu' \) -not -path 'tests/thirdparty/*' -not -path 'tests/abi/include/nlohmann/*' | sort)
 
       - name: Build patch and check for differences
         id: diff

.github/workflows/publish_documentation.yml

@@ -7,7 +7,6 @@ on:
       - develop
     paths:
       - docs/mkdocs/**
-      - docs/examples/**
   workflow_dispatch:
 
 # we don't want to have concurrent jobs, and we don't want to cancel running jobs to avoid broken publications

cmake/ci.cmake

@@ -294,7 +294,7 @@ file(GLOB_RECURSE INDENT_FILES
         ${PROJECT_SOURCE_DIR}/tests/src/*.cpp
         ${PROJECT_SOURCE_DIR}/tests/src/*.hpp
         ${PROJECT_SOURCE_DIR}/tests/benchmarks/src/benchmarks.cpp
-    ${PROJECT_SOURCE_DIR}/docs/examples/*.cpp
+    ${PROJECT_SOURCE_DIR}/docs/mkdocs/docs/examples/*.cpp
 )
 
 set(include_dir ${PROJECT_SOURCE_DIR}/single_include/nlohmann)

docs/mkdocs/docs/examples/parser_callback_t.cpp

@@ -9,13 +9,13 @@ int main()
     auto text = R"({"IDs": [116, 943], "Width": 800})";
 
     // discard the array when the parser reads its opening bracket
-    json j_array_start = json::parse(text, [](int /*depth*/, json::parse_event_t event, json & /*parsed*/)
+    json j_array_start = json::parse(text, [](int /*depth*/, json::parse_event_t event, json& /*parsed*/)
     {
         return event != json::parse_event_t::array_start;
     });
 
     // discard the same array when the parser reads its closing bracket
-    json j_array_end = json::parse(text, [](int /*depth*/, json::parse_event_t event, json & /*parsed*/)
+    json j_array_end = json::parse(text, [](int /*depth*/, json::parse_event_t event, json& /*parsed*/)
     {
         return event != json::parse_event_t::array_end;
     });
@@ -33,7 +33,7 @@ int main()
     });
 
     // discard the top-level object
-    json j_root = json::parse(text, [](int /*depth*/, json::parse_event_t event, json & /*parsed*/)
+    json j_root = json::parse(text, [](int /*depth*/, json::parse_event_t event, json& /*parsed*/)
     {
         return event != json::parse_event_t::object_end;
     });