search

Kotlin / dokka

API documentation engine for Kotlin
https://kotl.in/dokka
Apache License 2.0
3.45k stars 412 forks source link

ExternalDocumentationLink: Support older version provided by versioning plugin #2443

Open hfhbd opened 2 years ago

hfhbd commented 2 years ago

Is your feature request related to a problem? Please describe Ktor uses Dokka with the versioning plugin. The latest release of Ktor is 2.0.0, so it has many api changes. I still use an older version of Ktor (1.6.8) and use externalDocumentationLink to reference to Ktor. The docs url for ktor is: https://api.ktor.io for the latest version and https://api.ktor.io/older/ for older versions. The last release before 2.0.0 was 1.6.8, so I use externalDocumentationLink("https://api.ktor.io/").

Problem: After a new release of ktor, I have to change my gradle script and to regenerate my docs, because the docs for Ktor 1.6.8 has moved from https://api.ktor.io to https://api.ktor.io/older/1.6.8.

Describe the solution you'd like I don't want to update my docs (theoretically only the links to ktor) just because ktor released a new version.

  1. The version plugin should create a link even for the latest version with the version, here https://api.ktor.io/older/2.0.0, to always allow specifying a version.
  2. Always create a link for the latest version for libs with does not use versioning plugin at all, to simplify link generation logic inside dokka.
  3. At building my docs, dokka should fetch the used version from the class path and the version-list file from https://api.ktor.io to get the right path (because versioning plugin allows a custom folder, default older).

With this changes, dokka always generates links to https://api.ktor.io/older/$version/..., and use the version from the classpath.

Describe alternatives you've considered Drop the customization of the folder in the versioning plugin and use always the version directly. This allows to build docs with correct links even offline.

Workaround Every time a used dependency is updated you have to specify the older path manually and to regenerate and publish docs again...

Additional context Support using different version of the same library would be nice too, but not required in first step. eg ktor-server 1.6.8 in my backend module but ktor-client 2.0.0 in my frontend module.

Are you willing to provide a PR? With help, sure

martinbonnin commented 8 months ago

+1 I'd replace older with just the version name and 2.0.0 (or latest, configurable) for the current one:

api.example.com/2.0.0
api.example.com/1.6.8
...

It's much easier to do pattern matching, more predictable and also "older" might have a negative connotation in some contexts. Just using the version name is more descriptive.