The API docs (Dokka) seem to overwrite each other

[CLOVIS-AI]

What version are you currently using?

This is about the hosted API docs in the Arrow website.

Current (buggy) situation

• from the Arrow Core page, the link is https://arrow-kt.io/docs/apidocs/arrow-core/arrow.core/
• going up one navigation level from the linked page (top left button "arrow-core") sends to https://arrow-kt.io/docs/apidocs/index.html, which, despite the URL, is the arrow-optics-reflect documentation, and provides no link to the other modules
• I can't find the path to the package-list file (by default Dokka would have put it in https://arrow-kt.io/docs/apidocs/package-list)

What would you like to see?

The website to be configured correctly such that:

• there is a single frontpage with all Arrow modules
• I can configure Dokka in my own projects to link to all Arrow API docs

For reference, here is the Gradle configuration for Dokka 1.7.20 to add links to the KotlinX.Coroutines dokka pages:

tasks.withType<org.jetbrains.dokka.gradle.DokkaTaskPartial>().configureEach {
	dokkaSourceSets.configureEach {
		externalDocumentationLink {
			url.set(URL("https://kotlinlang.org/api/kotlinx.coroutines/"))
		}
	}
}

From this configuration, Dokka is able to find the https://kotlinlang.org/api/kotlinx.coroutines/package-list file which it uses to generate the links (that's the extent of my Dokka knowledge, sorry if I can't help more).

I know that the default Dokka configuration generates the file correctly (I did set up multiple of my projects to reference each other), so it should work more or less out of the box for Arrow as well (though I don't know what post processing is done in your case).

[franciscodr]

Hi @CLOVIS-AI, first of all, thanks for reporting this bug about the API documentation.

We have solved the issue that prevented you from accessing all the Arrow modules from the navigation menu.

Additionally, the package-list file is already accessible from this URL: https://arrow-kt.io/docs/apidocs/package-list

Please let us know if the error persists or if there are more unexpected behavior in the API documentation. Thanks!

[CLOVIS-AI]

Thanks, I will try this.

[CLOVIS-AI]

Hi, it seems this is may not be the correct path? I get:

Failed to download package-list from https://arrow-kt.io/docs/package-list, this might suggest that remote resource is not available, module is empty or dokka output got corrupted

To reproduce, create a Dokka project with the following configuration:

tasks.withType<org.jetbrains.dokka.gradle.DokkaTaskPartial>().configureEach {
	dokkaSourceSets.configureEach {
		externalDocumentationLink {
			url.set(URL("https://kotlinlang.org/api/kotlinx.coroutines/"))
		}
		externalDocumentationLink {
			url.set(URL("https://arrow-kt.io/docs/apidocs"))
		}
	}
}

The first link will resolve successfully to KotlinX.Coroutines, but the second prints the error.

[CLOVIS-AI]

Nevermind, the trailing slash seems to be necessary. The URL https://arrow-kt.io/docs/apidocs/ works. Thanks a lot for fixing this :)

[CLOVIS-AI]

Looks like it's gone again :/

https://gitlab.com/opensavvy/decouple/-/jobs/4143887014#L671

[CLOVIS-AI]

@nomisRev told me it has been moved to https://apidocs.arrow-kt.io/package-list. I'll try to change it on my side and will report back.

[CLOVIS-AI]

For anyone reading this in the future: Dokka is quite sensitive with how the URL is formatted:

• https://apidocs.arrow-kt.io: works
• https://apidocs.arrow-kt.io/: doesn't complain, but doesn't create links either
• https://apidocs.arrow-kt.io/package-list: doesn't complain, creates links, but they all 404
• Dokka will complain about other links

[nomisRev]

@CLOVIS-AI is that something we should report to Dokka?

[CLOVIS-AI]

I don't know. Their documentation is not very clear, and I have yet to see another project that actually sets this up…

[serras]

This has been solved in the new website, and API Docs show all modules.