Generate JSON docs statically (#112)

* Generate JSON docs statically

* Ensure example domains are FQDNs

Author: NelsonVides

.gitignore

@@ -8,9 +8,6 @@ asngen
 src/dns_zone_lexer.erl
 src/dns_zone_parser.erl
 
-# Generated documentation
-src/JSON_FORMAT.md
-
 # local setup
 .tool-versions
 

Makefile

@@ -50,5 +50,6 @@ rfc-list-print:
 	./scripts/generate_rfc_list.escript
 
 .PHONY: check-no-change-action
-check-no-change-action: rfc-list
+check-no-change-action: rfc-list json-docs
+	git diff --quiet --exit-code src/JSON_FORMAT.md
 	git diff --quiet --exit-code SUPPORTED_RFCS.md

rebar.config

@@ -36,8 +36,7 @@
     {test, [
         {deps, [{proper, "~> 1.5"}]},
         {erl_opts, [nowarn_export_all, nowarn_missing_spec, nowarn_missing_doc]},
-        {eunit_opts, [verbose]},
-        {covertool, [{coverdata_files, ["eunit.coverdata", "ct.coverdata"]}]},
+        {covertool, [{coverdata_files, ["ct.coverdata"]}]},
         {cover_excl_mods, [dns_zone_lexer, dns_zone_parser]},
         {cover_opts, [verbose, {min_coverage, 80}]},
         {cover_export_enabled, true},
@@ -50,12 +49,6 @@
     {post, [{clean, {asn, clean}}]}
 ]}.
 
-{pre_hooks, [
-    %% Generate JSON_FORMAT.md before ex_doc
-    {compile, "escript scripts/generate_json_docs.escript --output src/JSON_FORMAT.md || true"},
-    {edoc, "escript scripts/generate_json_docs.escript --output src/JSON_FORMAT.md || true"}
-]}.
-
 {dialyzer, [
     {warnings, [
         no_return,

scripts/generate_json_docs.escript

@@ -408,16 +408,19 @@ extract_binary_key_regex(Expr) ->
 generate_documentation(Records, EncodingRules, KeyMappings) ->
     InitAcc =
         ~"""
+        # JSON format
+
         This document describes the JSON encoding format for all DNS record types.
 
         ## Format Structure
 
         ### Resource Records (RR)
 
         Resource records (`dns_rr`) are encoded as follows:
+
         ```json
         {
-          "name": "example.com",
+          "name": "example.com.",
           "type": "A",
           "class": "in",
           "ttl": 3600,
@@ -428,6 +431,7 @@ generate_documentation(Records, EncodingRules, KeyMappings) ->
         ```
 
         The format includes:
+
         - `name`: Domain name (binary)
         - `type`: DNS type name as uppercase string (e.g., "A", "AAAA", "MX")
         - `ttl`: Time to live (integer)
@@ -437,6 +441,7 @@ generate_documentation(Records, EncodingRules, KeyMappings) ->
         ### Other Records
 
         Non-RR records (message, query, OPT records) use a two-level nested map format:
+
         - Outer key: Record type identifier (descriptive name)
         - Inner map: Record fields with binary keys
 
@@ -662,7 +667,7 @@ encoding_description(direct, FieldName, TypeStr) ->
         ip ->
             ~"IP address as string";
         svc_params when HasSvcbParams ->
-            ~"Map of SVCB service parameters (see [SVCB Service Parameters below](#module-svcb-service-parameters))";
+            ~"Map of SVCB service parameters (see [SVCB Service Parameters below](#svcb-service-parameters))";
         _ when HasDname orelse HasBinary -> ~"Binary data (dname format)";
         _ ->
             ~"Direct value"
@@ -694,6 +699,7 @@ generate_example(RecordName, Fields, KeyBin, Acc, EncodingRules) ->
     ),
     <<
         Acc/binary,
+        "\n",
         "**Example:**\n\n",
         "```json\n",
         "{\n",
@@ -717,10 +723,11 @@ generate_example_rr_format(_Fields, Acc) ->
     %% showing the structure with common fields
     <<
         Acc/binary,
+        "\n",
         "**Example:**\n\n",
         "```json\n",
         "{\n",
-        "  \"name\": \"example.com\",\n",
+        "  \"name\": \"example.com.\",\n",
         "  \"type\": \"A\",\n",
         "  \"class\": \"IN\",\n",
         "  \"ttl\": 3600,\n",
@@ -729,6 +736,7 @@ generate_example_rr_format(_Fields, Acc) ->
         "  }\n",
         "}\n",
         "```\n\n",
+        "\n",
         "**Note:** The `data` field contains the RRDATA-specific fields. ",
         "The `class` field is optional and defaults to `\"IN\"` if omitted. ",
         "See individual RRDATA record types below for complete field documentation.\n\n"
@@ -743,13 +751,15 @@ generate_example_rrdata_format(RecordName, Fields, Acc, EncodingRules) ->
     ExampleFieldsStr = format_example_fields(Fields, FieldNameFun, RecordName, EncodingRules),
     <<
         Acc/binary,
+        "\n",
         "**Example:**\n\n",
         "```json\n",
         "{\n",
         ExampleFieldsStr/binary,
         "\n",
         "}\n",
         "```\n\n",
+        "\n",
         "**Note:** This format is used within the `data` field of `dns_rr` records.\n\n"
     >>.
 
@@ -814,13 +824,14 @@ example_category_map() ->
 example_value_map() ->
     #{
         ip => ~"\"192.168.1.1\"",
-        name => ~"\"example.com\"",
-        dname => ~"\"example.com\"",
-        hostname => ~"\"example.com\"",
-        exchange => ~"\"mail.example.com\"",
-        target => ~"\"target.example.com\"",
-        mname => ~"\"ns1.example.com\"",
-        rname => ~"\"admin.example.com\"",
+        name => ~"\"example.com.\"",
+        dname => ~"\"example.com.\"",
+        hostname => ~"\"example.com.\"",
+        exchange => ~"\"mail.example.com.\"",
+        target => ~"\"target.example.com.\"",
+        target_name => ~"\"target.example.com.\"",
+        mname => ~"\"ns1.example.com.\"",
+        rname => ~"\"admin.example.com.\"",
         ttl => ~"3600",
         svc_params => ~"{\"alpn\": [\"h2\", \"h3\"], \"port\": 443}"
     }.
@@ -914,7 +925,7 @@ generate_svcb_params_section() ->
     ```json
     {
         "svc_priority": 1,
-        "target_name": "target.example.com",
+        "target_name": "target.example.com.",
         "svc_params": {
             "mandatory": ["alpn", "port"],
             "alpn": ["h2", "h3"],