New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation generation is flaky #2596
Comments
When we run this through dackka, we notice the heightened flake rate for all files in the root of the package tree like |
If a quick fix happened to slow down the file writing step, I don't think that would be too much of an issue for us, based on the times that dokka prints out for us on the androidx checkout (unless
|
I notice that you have no test for written files, only for files stored in the |
This bug was in error; I misread a The actual issue upstream is not missing files, but changed files. We had a missing file issue I have since fixed. The bug title still applies, however. I see changes primarily in link resolution, but also in API type resolution. For example, I found, in
Roughly 400 files had diffs (as above), most of which were link resolution in docs. I believe the API resolution issue is another case of external/classpath references not resolving, though instead of becoming The heightened rate of difference appearing in You do still seem to have no tests for written files, though, which could be a gap in coverage. |
I have investigated this. There are flaky html pages, including |
It looks like the The first one is due to us lumping all multiplatform files into a single sourceSet at the moment. |
Describe the bug
When running dokka, some files are not generated. This can apparently happen to any file, though it seems orders of magnitude more common for
index.html
and other files near the root of the output hierarchy. I suspect that this is due to file lock contention by the output writer.We first discovered this by adding code that enforces that all expected files in our dackka integration tests ("goldens") were actually generated (previously we had only enforced that all generated files were expected).
This seems like it would be a huge problem for us and for you, because it could result in missing files in
developer.android.com
/kotlinlang.org
(depending on how your update process works and how it removes files that are intended to cease being generated from one version to the next.)From a test and a rough estimate, out of 130,000 files generated by running unmodified upstream dokka on
androidx
framework/support
, 400 files were generated in the second run that were not generated in the first. Around a quarter of these (100 files) wereindex.html
, representing a flake rate forindex.html
of around20%
, and for other files of0.2%
.1.7.10
Replication process:
-Copy
frameworks/support
to anupstream-dokka
checkout.--Delete
compose/ui/ui-test/src/androidAndroidTest
because dokka fails if you don't (throws inorg.jetbrains.kotlin.types.expressions
--looks like the compiler).-run
./gradlew shadowJar
in the upstream checkout.-run
java -jar ./runners/cli/build/libs/dokka-cli-1.7.10-SNAPSHOT.jar -pluginsClasspath "./integration-tests/cli/build/libs/fat-base-plugin-1.7.10-SNAPSHOT.jar" -sourceSet "-src ./frameworks/support/"
in the upstream checkout.-add
dokka/root
togit
or otherwise copy it for later comparison.-run
java -jar ./runners/cli/build/libs/dokka-cli-1.7.10-SNAPSHOT.jar -pluginsClasspath "./integration-tests/cli/build/libs/fat-base-plugin-1.7.10-SNAPSHOT.jar" -sourceSet "-src ./frameworks/support/"
again.-notice that there is a diff (e.g.
git status
) between the docs generated by each run. I found roughly400
out of130,000
.html
files that were generated by the second run but not by the first.The text was updated successfully, but these errors were encountered: