OkHttp documentation not compatible with Dokka externalDocumentationLink
JayNewstrom opened this issue · comments
I'm trying to link to OkHttp documentation from another project https://okta.github.io/okta-mobile-kotlin/auth-foundation/com.okta.authfoundation.credential/-credential/access-token-interceptor.html
As you can see, the link generated by Dokka is https://square.github.io/okhttp/4.x/okhttp/okhttp3/-interceptor/index.md when it should be https://square.github.io/okhttp/4.x/okhttp/okhttp3/-interceptor/
I think this is due to how the docs are generated (markdown instead of html). Generation happens here: https://github.com/square/okhttp/blob/master/deploy_website.sh#L27 which generates a package-list file located here: https://github.com/square/okhttp/blob/gh-pages/4.x/okhttp/package-list
As you can see the generated package-list has suffixes for index.md on most pages, but they're not hosted at that location.
As an example of a well behaving doc site, I'm using https://kotlin.github.io/kotlinx.serialization/ which does link properly in the docs I'm trying to link from: https://okta.github.io/okta-mobile-kotlin/auth-foundation/com.okta.authfoundation.claims/-claims-provider/deserialize-claims.html
My linking to OkHttp can be found here: https://github.com/okta/okta-mobile-kotlin/blob/jn-dokka-gh-pages/build.gradle#L75
I published a modified version of the package-list that can be referenced here: https://colinwhite.me/okhttp3-package-list
I think this can be solved by adding a step after here that updates the package-list entries to html. I'll take a look later.
Any chance this is improved with recent dokka versions? We've just bumped to 1.7.10 IIRC.
@yschimke I don't think so unfortunately. I think it's because OkHttp builds the docs using GFM and then mkdocs uses those files to create a static site. The package-list still tells other libraries linking to it to look for .md files when there are none.
I think Dokka would have to add support for building with GFM, but emitting an HTML package list, which seems like a niche use case. Probably the easiest fix is to modify the package-list using something like sed.
@colinrtwhite Care to take a look? I won't be 100% sure it worked until the next release, but I have a local test #7414