Test GFM output against golden files

.pre-commit-config.yaml

@@ -3,7 +3,9 @@ repos:
     rev: v6.0.0
     hooks:
       - id: end-of-file-fixer
+        exclude: ^tests/integration/fixtures/
       - id: trailing-whitespace
+        exclude: ^tests/integration/fixtures/
       - id: check-yaml
       - id: check-added-large-files
 

MODULE.bazel

@@ -8,6 +8,7 @@ bazel_dep(name = "rules_java", version = "9.3.0")
 bazel_dep(name = "rules_jvm_external", version = "7.1")
 bazel_dep(name = "rules_kotlin", version = "2.4.0")
 
+bazel_dep(name = "bazel_lib", version = "3.1.0", dev_dependency = True)
 bazel_dep(name = "bazel_skylib", version = "1.9.0", dev_dependency = True)
 bazel_dep(name = "buildifier_prebuilt", version = "8.2.1.2", dev_dependency = True)
 bazel_dep(name = "rules_shell", version = "0.6.1", dev_dependency = True)

tests/integration/BUILD.bazel

@@ -1,3 +1,5 @@
+load("@bazel_lib//lib:copy_to_directory.bzl", "copy_to_directory")
+load("@bazel_lib//lib:diff_test.bzl", "diff_test")
 load("@rules_shell//shell:sh_test.bzl", "sh_test")
 load("//dokka:defs.bzl", "dokka", "dokka_config", "dokka_multi_module")
 
@@ -24,6 +26,36 @@ dokka(
     module_name = "Example API",
 )
 
+copy_to_directory(
+    name = "actual_gfm_markdown",
+    srcs = [":gfm_docs"],
+    include_srcs_patterns = [
+        "*.md",
+        "**/*.md",
+    ],
+    replace_prefixes = {
+        "-example -a-p-i": "example-api",
+        "-example -a-p-i/com.example/-bar": "example-api/com.example/bar",
+        "-example -a-p-i/com.example/-bar/-bar.md": "example-api/com.example/bar/bar.md",
+        "-example -a-p-i/com.example/-foo": "example-api/com.example/foo",
+        "-example -a-p-i/com.example/-foo/-foo.md": "example-api/com.example/foo/foo.md",
+    },
+    root_paths = ["tests/integration/gfm_docs"],
+)
+
+copy_to_directory(
+    name = "expected_gfm_markdown",
+    srcs = glob(["fixtures/gfm_docs/**/*.md"]),
+    root_paths = ["tests/integration/fixtures/gfm_docs"],
+)
+
+diff_test(
+    name = "gfm_docs_diff_test",
+    failure_message = "Generated GFM documentation differs from its checked-in fixtures.",
+    file1 = ":expected_gfm_markdown",
+    file2 = ":actual_gfm_markdown",
+)
+
 dokka(
     name = "html_docs",
     srcs = glob(["src/main/kotlin/**/*.kt"]),
@@ -127,6 +159,7 @@ test_suite(
         ":configured_publication_docs_test",
         ":derived_module_defaults_test",
         ":generated_docs_test",
+        ":gfm_docs_diff_test",
         ":multi_module_docs_test",
     ],
 )

tests/integration/fixtures/gfm_docs/example-api/com.example/bar/bar.md

@@ -0,0 +1,6 @@
+//[Example API](../../../index.md)/[com.example](../index.md)/[Bar](index.md)/[Bar](-bar.md)
+
+# Bar
+
+[JVM]\
+constructor()

tests/integration/fixtures/gfm_docs/example-api/com.example/bar/index.md

@@ -0,0 +1,20 @@
+//[Example API](../../../index.md)/[com.example](../index.md)/[Bar](index.md)
+
+# Bar
+
+[JVM]\
+class [Bar](index.md)
+
+A second documented type.
+
+## Constructors
+
+| | |
+|---|---|
+| [Bar](-bar.md) | [JVM]<br>constructor() |
+
+## Functions
+
+| Name | Summary |
+|---|---|
+| [value](value.md) | [JVM]<br>fun [~~value~~](value.md)()<br>A deprecated function retained in the default documentation. |

tests/integration/fixtures/gfm_docs/example-api/com.example/bar/value.md

@@ -0,0 +1,16 @@
+//[Example API](../../../index.md)/[com.example](../index.md)/[Bar](index.md)/[value](value.md)
+
+# value
+
+[JVM]\
+fun [~~value~~](value.md)()
+
+---
+
+### Deprecated
+
+Use Foo.value instead
+
+---
+
+A deprecated function retained in the default documentation.

tests/integration/fixtures/gfm_docs/example-api/com.example/foo/foo.md

@@ -0,0 +1,6 @@
+//[Example API](../../../index.md)/[com.example](../index.md)/[Foo](index.md)/[Foo](-foo.md)
+
+# Foo
+
+[JVM]\
+constructor()

tests/integration/fixtures/gfm_docs/example-api/com.example/foo/index.md

@@ -0,0 +1,20 @@
+//[Example API](../../../index.md)/[com.example](../index.md)/[Foo](index.md)
+
+# Foo
+
+[JVM]\
+class [Foo](index.md)
+
+The public entry point for the example API.
+
+## Constructors
+
+| | |
+|---|---|
+| [Foo](-foo.md) | [JVM]<br>constructor() |
+
+## Functions
+
+| Name | Summary |
+|---|---|
+| [value](value.md) | [JVM]<br>fun [value](value.md)(): String<br>Returns a documented value. |

tests/integration/fixtures/gfm_docs/example-api/com.example/foo/value.md

@@ -0,0 +1,8 @@
+//[Example API](../../../index.md)/[com.example](../index.md)/[Foo](index.md)/[value](value.md)
+
+# value
+
+[JVM]\
+fun [value](value.md)(): String
+
+Returns a documented value.

tests/integration/fixtures/gfm_docs/example-api/com.example/index.md

@@ -0,0 +1,10 @@
+//[Example API](../../index.md)/[com.example](index.md)
+
+# Package-level declarations
+
+## Types
+
+| Name | Summary |
+|---|---|
+| [Bar](-bar/index.md) | [JVM]<br>class [Bar](-bar/index.md)<br>A second documented type. |
+| [Foo](-foo/index.md) | [JVM]<br>class [Foo](-foo/index.md)<br>The public entry point for the example API. |

tests/integration/fixtures/gfm_docs/index.md

@@ -0,0 +1,9 @@
+//[Example API](index.md)
+
+# Example API
+
+## Packages
+
+| Name |
+|---|
+| [com.example](-example -a-p-i/com.example/index.md) |