Empty publication when Kotlin plugin applied to subprojects, but not to root project (with apply=false)

CLOVIS-AI commented 11 months ago

Hi!

I have a project in which I applied the Dokkatoo plugin. I'm currently refactoring it to use convention plugins, and in the process something strange broke. I don't know how to debug it.

The project is structured as follows:

playground/
    app/build.gradle.kts
    core/build.gradle.kts
    build.gradle.kts

The :core project has Dokkatoo. The :app project doesn't. The root project has a dependency on :core.

Previously, I ran ./gradlew :dokkatooGeneratePublicationHtml to generate the HTML output. However, now, it only generates an empty build/dokka/core directory.

If I run ./gradlew dokkatooGenerate, I get the following link printed in the terminal: http://localhost:63342/playground/build/dokka/html/index.html. Opening that link in the browser does allow me to browse the generated documentation. However, that file doesn't exist. The build/dokka directory only contains a subdirectory called core, there are no other files.

What could be the cause? I don't understand how this can happen.

Reproduction:

Repository https://gitlab.com/opensavvy/playgrounds/gradle
Commit 6d3edba36598d9d4d1fc1e5906bf6be1f6b698d3

Other useful links:

Code of the opensavvyConventions.plugins.base convention plugin: here (unrelated to Dokka)
Code of the opensavvyConventions.plugins.root convention plugin: here (applies the plugin + the dependencies workaround)
Code of the opensavvyConventions.plugins.kotlin.library convention plugin: here (applies the plugin + configures the project name + includes the README, etc)

aSemy commented 11 months ago

Hey @CLOVIS-AI, thanks for the report. I appreciate you using Dokkatoo, and taking the time to improve it.

I had a look through the code and I couldn't see anything obviously wrong.

It's certainly not helpful that the localhost link to index.html 404s - I'll add a check to fix that.

My only guess is that since :core only has a single const val and no other code then Dokka won't generate anything. Could you try adding a class into :core?

I have some more questions to help investigate.

Could you show some output logs? I'd like to see what tasks are running and what tasks are being skipped.
There should be Dokka worker logs too, somewhere in the build/run directory of each subproject (not just the root one) where Dokkatoo is applied.
Did generating a Dokka HTML publication ever work? Before you migrated to the convention plugins in a separate repo, did ./gradlew :dokkatooGeneratePublicationHtml work?

CLOVIS-AI commented 11 months ago

My only guess is that since :core only has a single const val and no other code then Dokka won't generate anything. Could you try adding a class into :core?

If I run ./gradlew dokkaGenerate, I can open the page in the browser, and the message field is documented. However, the file on disk corresponding to the URL is empty.

Could you show some output logs? I'd like to see what tasks are running and what tasks are being skipped.

./gradlew :dokkatooGeneratePublicationHtml → output
./gradlew dokkatooGeneratePublicationHtml → output
./gradlew :dokkatooGenerate → output
./gradlew dokkatooGenerate → output

In all cases:

$ tree build/dokka
build/dokka
└── html
    └── core

In the first and third case, http://localhost:63342/playground/build/dokka/html/index.html 404s. In the second and fourth case, the website works (but the directory is still empty).

The most obvious difference I see is that the executions that expose the website correctly have:

:core:dokkatooGeneratePublicationHtml   
:core:logLinkDokkatooGeneratePublicationHtml

Could it be that the root project just doesn't find the :core project and thus cannot set the dependencies correctly?

There should be Dokka worker logs too, somewhere in the build/run directory of each subproject (not just the root one) where Dokkatoo is applied.

I assume you mean core/build/tmp/dokkatooGeneratePublicationHtml/dokka-worker.log. It seems it is only generated in the second and fourth cases, so I doubt you'll learn much from it.

Worker log

``` [PROGRESS] Executing DokkaGeneratorWorker with dokkaParameters: DokkaConfigurationImpl(moduleName=Playground Core, moduleVersion=DEV, outputDir=[REDACTED]/playground/core/build/dokka/html, cacheRoot=null, offlineMode=false, sourceSets=[DokkaSourceSetImpl(displayName=common, sourceSetID=:core/commonMain, classpath=[REDACTED], pluginsConfiguration=[PluginConfigurationImpl(fqPluginName=org.jetbrains.dokka.base.DokkaBase, serializationFormat=JSON, values={"customAssets":[],"customStyleSheets":[],"separateInheritedMembers":false,"mergeImplicitExpectActualDeclarations":false}), PluginConfigurationImpl(fqPluginName=org.jetbrains.dokka.versioning.VersioningPlugin, serializationFormat=JSON, values={"versionsOrdering":[],"olderVersions":[],"renderVersionsNavigationOnAllPages":true})], modules=[], failOnWarning=false, delayTemplateSubstitution=false, suppressObviousFunctions=true, includes=[], suppressInheritedMembers=false, finalizeCoroutines=false) [PROGRESS] Initializing plugins [INFO] Loaded plugins: [org.jetbrains.dokka.templates.TemplatingPlugin, org.jetbrains.dokka.base.DokkaBase, org.jetbrains.dokka.analysis.kotlin.descriptors.ide.IdeDescriptorAnalysisPlugin, org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin, org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin] [INFO] Loaded: [ ExtensionPoint: org.jetbrains.dokka.CoreExtensions/sourceToDocumentableTranslator, ExtensionPoint: org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin/docCommentParsers, ExtensionPoint: org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin/docCommentCreators, ExtensionPoint: org.jetbrains.dokka.CoreExtensions/postActions, ExtensionPoint: org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin/kotlinLightMethodChecker, ExtensionPoint: org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin/inheritDocTagContentProviders, ExtensionPoint: org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin/sourceRootsExtractor, ExtensionPoint: org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin/projectProvider, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/externalDocumentablesProvider, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/inheritanceBuilder, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/kotlinToJavaService, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/moduleAndPackageDocumentationReader, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/syntheticDocumentableDetector, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/sampleProviderFactory, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/fullClassHierarchyBuilder, ExtensionPoint: org.jetbrains.dokka.CoreExtensions/pageTransformer, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/kotlinAnalysis, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/documentableSourceLanguageParser, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/analysisContextCreator, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/mockApplicationHack, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/klibService, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/descriptorFinder, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/kdocFinder, ExtensionPoint: org.jetbrains.dokka.base.DokkaBase/immediateHtmlCommandConsumer, ExtensionPoint: org.jetbrains.dokka.base.DokkaBase/htmlPreprocessors, ExtensionPoint: org.jetbrains.dokka.base.DokkaBase/outputWriter, ExtensionPoint: org.jetbrains.dokka.base.DokkaBase/externalLocationProviderFactory, ExtensionPoint: org.jetbrains.dokka.base.DokkaBase/locationProviderFactory, ExtensionPoint: org.jetbrains.dokka.CoreExtensions/renderer, ExtensionPoint: org.jetbrains.dokka.base.DokkaBase/pageMergerStrategy, ExtensionPoint: org.jetbrains.dokka.base.DokkaBase/commentsToContentConverter, ExtensionPoint: org.jetbrains.dokka.CoreExtensions/documentableToPageTranslator, ExtensionPoint: org.jetbrains.dokka.CoreExtensions/documentableTransformer, ExtensionPoint: org.jetbrains.dokka.base.DokkaBase/signatureProvider, ExtensionPoint: org.jetbrains.dokka.base.DokkaBase/preMergeDocumentableTransformer, ExtensionPoint: org.jetbrains.dokka.CoreExtensions/documentableMerger, ExtensionPoint: org.jetbrains.dokka.CoreExtensions/generation, ExtensionPoint: org.jetbrains.dokka.templates.TemplatingPlugin/directiveBasedCommandHandlers, ExtensionPoint: org.jetbrains.dokka.templates.TemplatingPlugin/substitutor, ExtensionPoint: org.jetbrains.dokka.templates.TemplatingPlugin/templateProcessingStrategy, ExtensionPoint: org.jetbrains.dokka.templates.TemplatingPlugin/multimoduleTemplateProcessor, ExtensionPoint: org.jetbrains.dokka.templates.TemplatingPlugin/submoduleTemplateProcessor, Extension: org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin/psiToDocumentableTranslator, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/descriptorToDocumentableTranslator, Extension: org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin/javaDocCommentParser, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/kotlinDocCommentParser, Extension: org.jetbrains.dokka.analysis.java.JavaAnalysisPlugin/javaDocCommentCreator, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/kotlinDocCommentCreator, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/disposeKotlinAnalysisPostAction, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/kotlinLightMethodChecker, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/inheritDocTagProvider, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/sourceRootsExtractor, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/projectProvider, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/defaultExternalDocumentablesProvider, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/descriptorInheritanceBuilder, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/kotlinToJavaMapper, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/moduleAndPackageDocumentationReader, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/descriptorSyntheticDocumentableDetector, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/kotlinSampleProviderFactory, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/descriptorFullClassHierarchyBuilder, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/defaultSamplesTransformer, Extension: org.jetbrains.dokka.base.DokkaBase/defaultSamplesTransformer, Extension: org.jetbrains.dokka.base.DokkaBase/sourceSetMerger, Extension: org.jetbrains.dokka.base.DokkaBase/pageMerger, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/defaultKotlinAnalysis, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.compiler.CompilerDescriptorAnalysisPlugin/documentableAnalyzerImpl, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.ide.IdeDescriptorAnalysisPlugin/ideAnalysisContextCreator, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.ide.IdeDescriptorAnalysisPlugin/ideApplicationHack, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.ide.IdeDescriptorAnalysisPlugin/ideKlibService, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.ide.IdeDescriptorAnalysisPlugin/ideDescriptorFinder, Extension: org.jetbrains.dokka.analysis.kotlin.descriptors.ide.IdeDescriptorAnalysisPlugin/ideKdocFinder, Extension: org.jetbrains.dokka.base.DokkaBase/pathToRootConsumer, Extension: org.jetbrains.dokka.base.DokkaBase/replaceVersionConsumer, Extension: org.jetbrains.dokka.base.DokkaBase/resolveLinkConsumer, Extension: org.jetbrains.dokka.base.DokkaBase/rootCreator, Extension: org.jetbrains.dokka.base.DokkaBase/sourcesetDependencyAppender, Extension: org.jetbrains.dokka.base.DokkaBase/packageListCreator, Extension: org.jetbrains.dokka.base.DokkaBase/assetsInstaller, Extension: org.jetbrains.dokka.base.DokkaBase/stylesInstaller, Extension: org.jetbrains.dokka.base.DokkaBase/scriptsInstaller, Extension: org.jetbrains.dokka.base.DokkaBase/customResourceInstaller, Extension: org.jetbrains.dokka.base.DokkaBase/navigationPageInstaller, Extension: org.jetbrains.dokka.base.DokkaBase/sourceLinksTransformer, Extension: org.jetbrains.dokka.base.DokkaBase/baseSearchbarDataInstaller, Extension: org.jetbrains.dokka.base.DokkaBase/fileWriter, Extension: org.jetbrains.dokka.base.DokkaBase/dokkaLocationProvider, Extension: org.jetbrains.dokka.base.DokkaBase/javadocLocationProvider, Extension: org.jetbrains.dokka.base.DokkaBase/locationProvider, Extension: org.jetbrains.dokka.base.DokkaBase/htmlRenderer, Extension: org.jetbrains.dokka.base.DokkaBase/sameMethodNameMerger, Extension: org.jetbrains.dokka.base.DokkaBase/fallbackMerger, Extension: org.jetbrains.dokka.base.DokkaBase/docTagToContentConverter, Extension: org.jetbrains.dokka.base.DokkaBase/documentableToPageTranslator, Extension: org.jetbrains.dokka.base.DokkaBase/extensionsExtractor, Extension: org.jetbrains.dokka.base.DokkaBase/undocumentedCodeReporter, Extension: org.jetbrains.dokka.base.DokkaBase/inheritorsExtractor, Extension: org.jetbrains.dokka.base.DokkaBase/actualTypealiasAdder, Extension: org.jetbrains.dokka.base.DokkaBase/kotlinSignatureProvider, Extension: org.jetbrains.dokka.base.DokkaBase/modulesAndPackagesDocumentation, Extension: org.jetbrains.dokka.base.DokkaBase/kotlinArrayDocumentableReplacer, Extension: org.jetbrains.dokka.base.DokkaBase/inheritedEntriesVisbilityFilter, Extension: org.jetbrains.dokka.base.DokkaBase/obviousFunctionsVisbilityFilter, Extension: org.jetbrains.dokka.base.DokkaBase/documentableVisibilityFilter, Extension: org.jetbrains.dokka.base.DokkaBase/suppressedBySuppressTagDocumentableFilter, Extension: org.jetbrains.dokka.base.DokkaBase/suppressedDocumentableFilter, Extension: org.jetbrains.dokka.base.DokkaBase/deprecatedDocumentableFilter, Extension: org.jetbrains.dokka.base.DokkaBase/emptyPackagesFilter, Extension: org.jetbrains.dokka.base.DokkaBase/emptyModulesFilter, Extension: org.jetbrains.dokka.base.DokkaBase/documentableMerger, Extension: org.jetbrains.dokka.base.DokkaBase/singleGeneration, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/replaceVersionCommandHandler, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/substitutionCommandHandler, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/addToNavigationCommandHandler, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/projectNameSubstitutor, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/pathToRootSubstitutor, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/packageListProcessingStrategy, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/pagesSearchTemplateStrategy, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/sourcesetDependencyProcessingStrategy, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/directiveBasedHtmlTemplateProcessingStrategy, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/fallbackProcessingStrategy, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/defaultMultiModuleTemplateProcessor, Extension: org.jetbrains.dokka.templates.TemplatingPlugin/defaultSubmoduleTemplateProcessor ] [INFO] Suppressed: [ ] [PROGRESS] Dokka is performing: documentation for Playground Core [PROGRESS] Validity check [PROGRESS] Creating documentation models [INFO] logging: loading modules: [java.se, jdk.accessibility, jdk.attach, jdk.compiler, jdk.dynalink, jdk.httpserver, jdk.incubator.foreign, jdk.incubator.vector, jdk.jartool, jdk.javadoc, jdk.jconsole, jdk.jdi, jdk.jfr, jdk.jshell, jdk.jsobject, jdk.management, jdk.management.jfr, jdk.net, jdk.nio.mapmode, jdk.sctp, jdk.security.auth, jdk.security.jgss, jdk.unsupported, jdk.unsupported.desktop, jdk.xml.dom, java.base, java.compiler, java.datatransfer, java.desktop, java.xml, java.instrument, java.logging, java.management, java.management.rmi, java.rmi, java.naming, java.net.http, java.prefs, java.scripting, java.security.jgss, java.security.sasl, java.sql, java.transaction.xa, java.sql.rowset, java.xml.crypto, jdk.internal.jvmstat, jdk.management.agent, jdk.jdwp.agent, jdk.internal.ed, jdk.internal.le, jdk.internal.opt] [PROGRESS] Transforming documentation model before merging [PROGRESS] Merging documentation models [PROGRESS] Transforming documentation model after merging [PROGRESS] Creating pages [PROGRESS] Transforming pages [PROGRESS] Rendering [PROGRESS] Running post-actions [INFO] Unused extension points found: ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/externalDocumentablesProvider, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/inheritanceBuilder, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/kotlinToJavaService, ExtensionPoint: org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin/syntheticDocumentableDetector, ExtensionPoint: org.jetbrains.dokka.templates.TemplatingPlugin/directiveBasedCommandHandlers, ExtensionPoint: org.jetbrains.dokka.templates.TemplatingPlugin/substitutor, ExtensionPoint: org.jetbrains.dokka.templates.TemplatingPlugin/templateProcessingStrategy, ExtensionPoint: org.jetbrains.dokka.templates.TemplatingPlugin/multimoduleTemplateProcessor, ExtensionPoint: org.jetbrains.dokka.templates.TemplatingPlugin/submoduleTemplateProcessor [INFO] Generation completed successfully [PROGRESS] [INFO] === TIME MEASUREMENT === [INFO] Initializing plugins: 399 [INFO] Validity check: 0 [INFO] Creating documentation models: 990 [INFO] Transforming documentation model before merging: 42 [INFO] Merging documentation models: 0 [INFO] Transforming documentation model after merging: 10 [INFO] Creating pages: 261 [INFO] Transforming pages: 5 [INFO] Rendering: 3480 [INFO] Running post-actions: 3 [INFO] DokkaGeneratorWorker completed in PT5.193743173S ```

Did generating a Dokka HTML publication ever work? Before you migrated to the convention plugins in a separate repo, did ./gradlew :dokkatooGeneratePublicationHtml work?

Yes. The last commit where it did work was f3759626465ad8f3839a1b6a36205002d06bdfcb. It's hard to provide a diff, because the only thing that changed is the convention plugins being extracted to another repository.

You can find the code for the convention plugins in gradle/conventions. They are essentially the same. Most importantly, they use the same version of Dokkatoo (2.0.0).

CLOVIS-AI commented 11 months ago

I managed to reproduce the issue using the sample in the convention plugin repository directly. This is more convenient, because it allows editing the plugins to try fixes.

To reproduce:

Clone https://gitlab.com/opensavvy/automation/gradle-conventions.git
Checkout the branch 11-fix-dokkatoo
In IntelliJ, open the file examples/kotlin/settings.gradle.kts as project, to ensure all modules are loaded
In IDEA's terminal, you should be in the directory examples/kotlin. Run ./gradlew :dokkatooGenerate (or any other command).

Asking Gradle to dump dependencies, I get

dokkatooModuleHtml - Fetch Dokka Module files for html from other subprojects
\--- project :core

which is the same as what I get with the old version (which worked). So, at least, it's not the dependencies block that's broken, but I don't know how to debug any further.

CLOVIS-AI commented 11 months ago

Interesting, I managed to reproduce the issue in a project that does not use the convention plugins at all (by simply inlining them), see the branch 11-reproduce-dokkatoo in https://gitlab.com/opensavvy/automation/gradle-conventions.git.

I'm currently diff-ing it with the version that works.

CLOVIS-AI commented 11 months ago

Uh, found the problems.

Incorrect fix for #14

Incorrect:

dependencies {
    // This is required at the moment, see https://github.com/adamko-dev/dokkatoo/issues/14
    dokkatoo.versions.jetbrainsDokka.map { dokkaVersion ->
        "org.jetbrains.dokka:all-modules-page-plugin:$dokkaVersion"
    }
}

Correct:

dependencies {
    // This is required at the moment, see https://github.com/adamko-dev/dokkatoo/issues/14
    dokkatooPluginHtml(
        dokkatoo.versions.jetbrainsDokka.map { dokkaVersion ->
            "org.jetbrains.dokka:all-modules-page-plugin:$dokkaVersion"
        }
    )
}

This lets Dokkatoo generate the output, but it only has the main page decorations, it doesn't actually contain the documentation of the :core module.

The root project must have the Kotlin plugin

Even if apply false, but it must be present.

For the first problem, well, an issue already exists. For the second problem, could you please add some kind of error when Dokkatoo is applied without the Kotlin plugin, since apparently it breaks the output? After that, I guess this issue is fixed.

CLOVIS-AI commented 11 months ago

Completely unrelated, but thanks for the great plugin! Essentially all my projects have migrated to it :)

aSemy commented 10 months ago

Thanks for the praise! I'm happy Dokkatoo is working out well for you!

I've had a bit of a further dig into the issues.

localhost link to index.html 404s

I've had an experiment of trying to disable the logging if the index.html file doesn't exist, or logging a warning if the URL 404s, and a few other ideas. And to be honest, I don't really feel like they worked well. It felt a bit janky, and over bearing, and sensitive. A 404 might be caused by index.html missing, but also maybe the webserver might be broken, or the URL is invalid. Trying to put some sort of warning in is a nice idea, but I'm thinking it's basically the same as the link 404ing, so adding a warning is redundant.

Maybe I could add a check in the 'generate HTML publication' task where if the index.html file isn't generated then it logs a warning, but again, it doesn't quite sit right with me. I'm not quite sure why, but I think it's because it just leads to more code and tests and things to go wrong!

In any case, at least my experiments mean I've added some basic tests!

The root project must have the Kotlin plugin

Ah yes, this is something I've noticed before, but I didn't make an issue for it.

https://github.com/adamko-dev/dokkatoo/blob/1a73111312b347ac21598f514abfcaa4952078b2/modules/dokkatoo-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt#L397C11-L399

Alternatively the plugin can be added to buildSrc/build.gradle.kts, like what Dokkatoo itself does (the root project doesn't apply false the Kotlin plugin)

https://github.com/adamko-dev/dokkatoo/blob/1a73111312b347ac21598f514abfcaa4952078b2/buildSrc/build.gradle.kts#L10

I'm not sure this is a Dokkatoo problem, or a Gradle problem. The buildscript classpath is weird stuff.

WDYT?

CLOVIS-AI commented 10 months ago

I wonder if there is a way to ask Gradle whether a plugin is on the classpath, and emit a warning if it isn't? That's a pretty big footgun, and it's really not easy to debug.

aSemy commented 10 months ago

That's a pretty big footgun, and it's really not easy to debug.

Welcome to Gradle :) Apparently is the 'plugin must be applied to the root project' is a Gradle problem, so I made an issue here https://github.com/gradle/gradle/issues/27218

I can certainly add a warning though. Something like

val kotlinExtension = project.extensions.findKotlinExtension()
if (kotlinExtension == null && project.extensions.findByName("kotlin") != null) {
  logger.warn("$dkaName could not get the Kotlin extension in ${project.path}")
}

in DokkatooKotlinAdapter

adamko-dev / dokkatoo