diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8e340c4..8cad308 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -3,9 +3,9 @@ repos: rev: v6.0.0 hooks: - id: end-of-file-fixer - exclude: ^tests/integration/fixtures/ + exclude: ^tests/integration/(?:[^/]+/)*fixtures/ - id: trailing-whitespace - exclude: ^tests/integration/fixtures/ + exclude: ^tests/integration/(?:[^/]+/)*fixtures/ - id: check-yaml - id: check-added-large-files diff --git a/tests/integration/BUILD.bazel b/tests/integration/BUILD.bazel index 0d0d8da..d4beea9 100644 --- a/tests/integration/BUILD.bazel +++ b/tests/integration/BUILD.bazel @@ -56,6 +56,13 @@ diff_test( file2 = ":actual_gfm_markdown", ) +diff_test( + name = "deps_diff_test", + failure_message = "Dokka did not resolve the API exposed by its compiled dependency.", + file1 = "//tests/integration/deps:expected_markdown", + file2 = "//tests/integration/deps:actual_markdown", +) + dokka( name = "html_docs", srcs = glob(["src/main/kotlin/**/*.kt"]), @@ -157,6 +164,7 @@ test_suite( name = "tests", tests = [ ":configured_publication_docs_test", + ":deps_diff_test", ":derived_module_defaults_test", ":generated_docs_test", ":gfm_docs_diff_test", diff --git a/tests/integration/deps/BUILD.bazel b/tests/integration/deps/BUILD.bazel new file mode 100644 index 0000000..872202c --- /dev/null +++ b/tests/integration/deps/BUILD.bazel @@ -0,0 +1,42 @@ +load("@bazel_lib//lib:copy_to_directory.bzl", "copy_to_directory") +load("@rules_kotlin//kotlin:jvm.bzl", "kt_jvm_library") +load("//dokka:defs.bzl", "dokka", "dokka_config") + +kt_jvm_library( + name = "dependency", + srcs = ["Dependency.kt"], + neverlink = True, +) + +dokka_config( + name = "config", + no_jdk_link = True, + no_stdlib_link = True, +) + +dokka( + name = "docs", + srcs = ["UsesDependency.kt"], + config = ":config", + format = "gfm", + module_name = "Dependency API", + deps = [":dependency"], +) + +copy_to_directory( + name = "actual_markdown", + srcs = [":docs"], + include_srcs_patterns = ["**/-uses-dependency/index.md"], + replace_prefixes = { + "-dependency -a-p-i/com.example/-uses-dependency": "uses-dependency", + }, + root_paths = ["tests/integration/deps/docs"], + visibility = ["//tests/integration:__pkg__"], +) + +copy_to_directory( + name = "expected_markdown", + srcs = glob(["fixtures/**/*.md"]), + root_paths = ["tests/integration/deps/fixtures"], + visibility = ["//tests/integration:__pkg__"], +) diff --git a/tests/integration/deps/Dependency.kt b/tests/integration/deps/Dependency.kt new file mode 100644 index 0000000..4f55b4a --- /dev/null +++ b/tests/integration/deps/Dependency.kt @@ -0,0 +1,7 @@ +package com.example.dependency + +/** A compiled dependency made available to Dokka through its analysis classpath. */ +open class Dependency { + /** A member inherited by the documented source. */ + fun inheritedValue(): String = "dependency" +} diff --git a/tests/integration/deps/UsesDependency.kt b/tests/integration/deps/UsesDependency.kt new file mode 100644 index 0000000..2c821e9 --- /dev/null +++ b/tests/integration/deps/UsesDependency.kt @@ -0,0 +1,6 @@ +package com.example + +import com.example.dependency.Dependency + +/** Public API that requires Dokka to resolve a type from a dependency class jar. */ +class UsesDependency : Dependency() diff --git a/tests/integration/deps/fixtures/uses-dependency/index.md b/tests/integration/deps/fixtures/uses-dependency/index.md new file mode 100644 index 0000000..2129f5e --- /dev/null +++ b/tests/integration/deps/fixtures/uses-dependency/index.md @@ -0,0 +1,20 @@ +//[Dependency API](../../../index.md)/[com.example](../index.md)/[UsesDependency](index.md) + +# UsesDependency + +[JVM]\ +class [UsesDependency](index.md) : Dependency + +Public API that requires Dokka to resolve a type from a dependency class jar. + +## Constructors + +| | | +|---|---| +| [UsesDependency](-uses-dependency.md) | [JVM]
constructor() | + +## Functions + +| Name | Summary | +|---|---| +| [inheritedValue](index.md#-1773915307%2FFunctions%2F-32162611) | [JVM]
fun [inheritedValue](index.md#-1773915307%2FFunctions%2F-32162611)(): String | \ No newline at end of file diff --git a/tests/rules/BUILD.bazel b/tests/rules/BUILD.bazel index fb061ff..9a0c375 100644 --- a/tests/rules/BUILD.bazel +++ b/tests/rules/BUILD.bazel @@ -98,6 +98,13 @@ dokka( tags = ["manual"], ) +dokka( + name = "deps_fixture", + srcs = ["DepsFixture.kt"], + tags = ["manual"], + deps = [":dependency"], +) + dokka( name = "docs", srcs = ["Fixture.kt"], diff --git a/tests/rules/DepsFixture.kt b/tests/rules/DepsFixture.kt new file mode 100644 index 0000000..3e2a9c8 --- /dev/null +++ b/tests/rules/DepsFixture.kt @@ -0,0 +1,6 @@ +package com.example + +/** A documented fixture whose public API uses a type supplied through `dokka.deps`. */ +class DepsFixture( + val dependency: Dependency, +) diff --git a/tests/rules/dokka_analysis_test.bzl b/tests/rules/dokka_analysis_test.bzl index b183839..52ca150 100644 --- a/tests/rules/dokka_analysis_test.bzl +++ b/tests/rules/dokka_analysis_test.bzl @@ -216,6 +216,28 @@ def _dokka_wasm_test_impl(ctx): return analysistest.end(env) +def _dokka_deps_test_impl(ctx): + env = analysistest.begin(ctx) + + for configuration_basename in [ + "deps_fixture.dokka.json", + "deps_fixture.dokka-partial.json", + ]: + write_action = _write_action_for_output(env, configuration_basename) + if write_action: + configuration = json.decode(write_action.content) + classpath = configuration["sourceSets"][0]["classpath"] + asserts.true(env, _contains_fragment(classpath, "dependency.abi.jar")) + + for mnemonic in ["Dokka", "DokkaPartial"]: + actions = _actions_with_mnemonic(env, mnemonic) + asserts.equals(env, 1, len(actions)) + if actions: + input_basenames = [file.basename for file in actions[0].inputs.to_list()] + asserts.true(env, "dependency.abi.jar" in input_basenames) + + return analysistest.end(env) + def _dokka_multi_module_test_impl(ctx): env = analysistest.begin(ctx) target = analysistest.target_under_test(env) @@ -417,6 +439,7 @@ def _non_html_module_test_impl(ctx): _dokka_configuration_test = analysistest.make(_dokka_configuration_test_impl) _dokka_defaults_test = analysistest.make(_dokka_defaults_test_impl) +_dokka_deps_test = analysistest.make(_dokka_deps_test_impl) _dokka_wasm_test = analysistest.make(_dokka_wasm_test_impl) _dokka_multi_module_test = analysistest.make(_dokka_multi_module_test_impl) _dokka_reusable_config_test = analysistest.make(_dokka_reusable_config_test_impl) @@ -459,6 +482,10 @@ def dokka_analysis_test_suite(name): name = name + "_defaults", target_under_test = ":defaults_fixture", ) + _dokka_deps_test( + name = name + "_deps", + target_under_test = ":deps_fixture", + ) _dokka_wasm_test( name = name + "_wasm", target_under_test = ":wasm_fixture", @@ -500,6 +527,7 @@ def dokka_analysis_test_suite(name): tests = [ ":" + name + "_configuration", ":" + name + "_defaults", + ":" + name + "_deps", ":" + name + "_duplicate_module_name", ":" + name + "_duplicate_module_path", ":" + name + "_invalid_config",