[WIP] Kickstart a documentation module

Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>

Author: jviotti

.github/workflows/website-build.yml

@@ -22,6 +22,7 @@ jobs:
           -DBLAZE_TEST:BOOL=OFF
           -DBLAZE_CONFIGURATION:BOOL=OFF
           -DBLAZE_ALTERSCHEMA:BOOL=OFF
+          -DBLAZE_DOCUMENTATION:BOOL=OFF
           -DBLAZE_TESTS:BOOL=OFF
           -DBLAZE_DOCS:BOOL=ON
       - run: cmake --build ./build --config Release --target doxygen

.github/workflows/website-deploy.yml

@@ -33,6 +33,7 @@ jobs:
           -DBLAZE_TEST:BOOL=OFF
           -DBLAZE_CONFIGURATION:BOOL=OFF
           -DBLAZE_ALTERSCHEMA:BOOL=OFF
+          -DBLAZE_DOCUMENTATION:BOOL=OFF
           -DBLAZE_TESTS:BOOL=OFF
           -DBLAZE_DOCS:BOOL=ON
       - run: cmake --build ./build --config Release --target doxygen

CMakeLists.txt

@@ -11,6 +11,7 @@ option(BLAZE_OUTPUT "Build the Blaze output formats library" ON)
 option(BLAZE_TEST "Build the Blaze test runner library" ON)
 option(BLAZE_CONFIGURATION "Build the Blaze configuration file library" ON)
 option(BLAZE_ALTERSCHEMA "Build the Blaze alterschema rule library" ON)
+option(BLAZE_DOCUMENTATION "Build the Blaze documentation generator library" ON)
 option(BLAZE_TESTS "Build the Blaze tests" OFF)
 option(BLAZE_BENCHMARK "Build the Blaze benchmarks" OFF)
 option(BLAZE_CONTRIB "Build the Blaze contrib programs" OFF)
@@ -67,6 +68,10 @@ if(BLAZE_ALTERSCHEMA)
   add_subdirectory(src/alterschema)
 endif()
 
+if(BLAZE_DOCUMENTATION)
+  add_subdirectory(src/documentation)
+endif()
+
 if(BLAZE_CONTRIB)
   add_subdirectory(contrib)
 endif()
@@ -118,6 +123,10 @@ if(BLAZE_TESTS)
     add_subdirectory(test/alterschema)
   endif()
 
+  if(BLAZE_DOCUMENTATION)
+    add_subdirectory(test/documentation)
+  endif()
+
   if(PROJECT_IS_TOP_LEVEL)
     # Otherwise we need the child project to link
     # against the sanitizers too.

config.cmake.in

@@ -10,6 +10,7 @@ if(NOT BLAZE_COMPONENTS)
   list(APPEND BLAZE_COMPONENTS test)
   list(APPEND BLAZE_COMPONENTS configuration)
   list(APPEND BLAZE_COMPONENTS alterschema)
+  list(APPEND BLAZE_COMPONENTS documentation)
 endif()
 
 include(CMakeFindDependencyMacro)
@@ -35,6 +36,8 @@ foreach(component ${BLAZE_COMPONENTS})
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_blaze_compiler.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_blaze_output.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_blaze_alterschema.cmake")
+  elseif(component STREQUAL "documentation")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_blaze_documentation.cmake")
   else()
     message(FATAL_ERROR "Unknown Blaze component: ${component}")
   endif()

doxygen/index.markdown

@@ -71,6 +71,7 @@ CMake
 | `BLAZE_EVALUATOR`           | Boolean | `ON`    | Build the Blaze evaluator library       |
 | `BLAZE_TEST`                | Boolean | `ON`    | Build the Blaze test runner library     |
 | `BLAZE_ALTERSCHEMA`         | Boolean | `ON`    | Build the Blaze alterschema rule library|
+| `BLAZE_DOCUMENTATION`       | Boolean | `ON`    | Build the Blaze documentation library   |
 | `BLAZE_TESTS`               | Boolean | `OFF`   | Build the Blaze tests                   |
 | `BLAZE_BENCHMARK`           | Boolean | `OFF`   | Build the Blaze benchmarks              |
 | `BLAZE_CONTRIB`             | Boolean | `OFF`   | Build the Blaze contrib programs        |

src/documentation/CMakeLists.txt

@@ -0,0 +1,14 @@
+sourcemeta_library(NAMESPACE sourcemeta PROJECT blaze NAME documentation
+  FOLDER "Blaze/Documentation"
+  SOURCES documentation.cc)
+
+if(BLAZE_INSTALL)
+  sourcemeta_library_install(NAMESPACE sourcemeta PROJECT blaze NAME documentation)
+endif()
+
+target_link_libraries(sourcemeta_blaze_documentation PUBLIC
+  sourcemeta::core::json)
+target_link_libraries(sourcemeta_blaze_documentation PUBLIC
+  sourcemeta::core::jsonschema)
+target_link_libraries(sourcemeta_blaze_documentation PRIVATE
+  sourcemeta::blaze::alterschema)

src/documentation/documentation.cc

@@ -0,0 +1,157 @@
+#include <sourcemeta/blaze/documentation.h>
+
+#include <sourcemeta/blaze/alterschema.h>
+
+#include <sourcemeta/core/jsonschema.h>
+
+#include <cassert> // assert
+#include <utility> // std::move
+
+namespace sourcemeta::blaze {
+
+namespace {
+
+auto type_expression_of(const sourcemeta::core::JSON &schema)
+    -> Documentation::Type::Expression {
+  Documentation::Type::Expression expression;
+
+  if (!schema.is_object()) {
+    return expression;
+  }
+
+  if (schema.defines("enum") && schema.at("enum").is_array()) {
+    Documentation::Type::Expression::Enumeration enumeration;
+    for (const auto &value : schema.at("enum").as_array()) {
+      enumeration.values.push_back(value);
+    }
+    expression.value = std::move(enumeration);
+    return expression;
+  }
+
+  if (schema.defines("type") && schema.at("type").is_string()) {
+    const auto &type{schema.at("type").to_string()};
+    if (type == "object") {
+      expression.value = Documentation::Type::Expression::Object{};
+    } else if (type == "string") {
+      expression.value = Documentation::Type::Expression::Primitive::String;
+    } else if (type == "integer") {
+      expression.value = Documentation::Type::Expression::Primitive::Integer;
+    } else if (type == "number") {
+      expression.value = Documentation::Type::Expression::Primitive::Number;
+    }
+  }
+
+  return expression;
+}
+
+auto notes_of(const sourcemeta::core::JSON &schema) -> Documentation::Notes {
+  Documentation::Notes notes;
+  if (!schema.is_object()) {
+    return notes;
+  }
+  if (schema.defines("title") && schema.at("title").is_string()) {
+    notes.title = schema.at("title").to_string();
+  }
+  if (schema.defines("description") && schema.at("description").is_string()) {
+    notes.description = schema.at("description").to_string();
+  }
+  if (schema.defines("default")) {
+    notes.default_value = schema.at("default");
+  }
+  return notes;
+}
+
+auto is_required_property(const sourcemeta::core::JSON &schema,
+                          const sourcemeta::core::JSON::String &property)
+    -> bool {
+  if (!schema.is_object() || !schema.defines("required") ||
+      !schema.at("required").is_array()) {
+    return false;
+  }
+  for (const auto &item : schema.at("required").as_array()) {
+    if (item.is_string() && item.to_string() == property) {
+      return true;
+    }
+  }
+  return false;
+}
+
+auto walk_schema(const sourcemeta::core::JSON &schema, const bool include_root)
+    -> Documentation;
+
+auto walk_properties(const sourcemeta::core::JSON &schema,
+                     std::vector<Documentation::Row> &rows) -> void {
+  if (!schema.is_object() || !schema.defines("properties") ||
+      !schema.at("properties").is_object()) {
+    return;
+  }
+
+  for (const auto &entry : schema.at("properties").as_object()) {
+    Documentation::Row row;
+    row.path = "/" + entry.first;
+    row.type.expression = type_expression_of(entry.second);
+    row.notes = notes_of(entry.second);
+    row.required = is_required_property(schema, entry.first);
+    rows.push_back(std::move(row));
+  }
+}
+
+auto walk_any_of(const sourcemeta::core::JSON &schema,
+                 std::vector<Documentation::Section> &children) -> void {
+  if (!schema.is_object() || !schema.defines("anyOf") ||
+      !schema.at("anyOf").is_array()) {
+    return;
+  }
+
+  Documentation::Section section;
+  section.label = "Any of";
+  for (const auto &branch : schema.at("anyOf").as_array()) {
+    section.children.push_back(walk_schema(branch, false));
+  }
+  children.push_back(std::move(section));
+}
+
+auto walk_schema(const sourcemeta::core::JSON &schema, const bool include_root)
+    -> Documentation {
+  Documentation documentation;
+
+  if (include_root) {
+    Documentation::Row root;
+    root.path = "(root)";
+    root.type.expression = type_expression_of(schema);
+    root.notes = notes_of(schema);
+    documentation.rows.push_back(std::move(root));
+  }
+
+  walk_properties(schema, documentation.rows);
+  walk_any_of(schema, documentation.children);
+
+  return documentation;
+}
+
+} // namespace
+
+auto to_documentation(const sourcemeta::core::JSON &schema,
+                      const sourcemeta::core::SchemaWalker &walker,
+                      const sourcemeta::core::SchemaResolver &resolver)
+    -> Documentation {
+  // Canonicalize the schema for easier analysis
+  sourcemeta::core::SchemaTransformer canonicalizer;
+  sourcemeta::blaze::add(canonicalizer,
+                         sourcemeta::blaze::AlterSchemaMode::Canonicalizer);
+  sourcemeta::core::JSON canonical{schema};
+  [[maybe_unused]] const auto canonicalized{canonicalizer.apply(
+      canonical, walker, resolver,
+      [](const auto &, const auto, const auto, const auto &,
+         [[maybe_unused]] const auto applied) { assert(applied); })};
+  assert(canonicalized.first);
+
+  // Frame the canonicalized schema with reference information
+  sourcemeta::core::SchemaFrame frame{
+      sourcemeta::core::SchemaFrame::Mode::References};
+  frame.analyse(canonical, walker, resolver);
+
+  return walk_schema(canonical, true);
+}
+
+} // namespace sourcemeta::blaze