diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8744eb3..8e340c4 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/MODULE.bazel b/MODULE.bazel index fb98648..e806775 100644 --- a/MODULE.bazel +++ b/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) diff --git a/tests/integration/BUILD.bazel b/tests/integration/BUILD.bazel index feb513b..0d0d8da 100644 --- a/tests/integration/BUILD.bazel +++ b/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", ], ) diff --git a/tests/integration/fixtures/gfm_docs/example-api/com.example/bar/bar.md b/tests/integration/fixtures/gfm_docs/example-api/com.example/bar/bar.md new file mode 100644 index 0000000..2a0edcf --- /dev/null +++ b/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() \ No newline at end of file diff --git a/tests/integration/fixtures/gfm_docs/example-api/com.example/bar/index.md b/tests/integration/fixtures/gfm_docs/example-api/com.example/bar/index.md new file mode 100644 index 0000000..b38e915 --- /dev/null +++ b/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]
constructor() | + +## Functions + +| Name | Summary | +|---|---| +| [value](value.md) | [JVM]
fun [~~value~~](value.md)()
A deprecated function retained in the default documentation. | \ No newline at end of file diff --git a/tests/integration/fixtures/gfm_docs/example-api/com.example/bar/value.md b/tests/integration/fixtures/gfm_docs/example-api/com.example/bar/value.md new file mode 100644 index 0000000..546545e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/tests/integration/fixtures/gfm_docs/example-api/com.example/foo/foo.md b/tests/integration/fixtures/gfm_docs/example-api/com.example/foo/foo.md new file mode 100644 index 0000000..7594e11 --- /dev/null +++ b/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() \ No newline at end of file diff --git a/tests/integration/fixtures/gfm_docs/example-api/com.example/foo/index.md b/tests/integration/fixtures/gfm_docs/example-api/com.example/foo/index.md new file mode 100644 index 0000000..c6ab55f --- /dev/null +++ b/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]
constructor() | + +## Functions + +| Name | Summary | +|---|---| +| [value](value.md) | [JVM]
fun [value](value.md)(): String
Returns a documented value. | \ No newline at end of file diff --git a/tests/integration/fixtures/gfm_docs/example-api/com.example/foo/value.md b/tests/integration/fixtures/gfm_docs/example-api/com.example/foo/value.md new file mode 100644 index 0000000..e0657f5 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/tests/integration/fixtures/gfm_docs/example-api/com.example/index.md b/tests/integration/fixtures/gfm_docs/example-api/com.example/index.md new file mode 100644 index 0000000..4bc96ce --- /dev/null +++ b/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]
class [Bar](-bar/index.md)
A second documented type. | +| [Foo](-foo/index.md) | [JVM]
class [Foo](-foo/index.md)
The public entry point for the example API. | \ No newline at end of file diff --git a/tests/integration/fixtures/gfm_docs/index.md b/tests/integration/fixtures/gfm_docs/index.md new file mode 100644 index 0000000..119322d --- /dev/null +++ b/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) | \ No newline at end of file