Link to external Dokka/Javadoc sites' package-list files

[cjbrooks12]

Orchid has a mechanism for linking to external sites, but it only reads from its internal JSON format, currently. It should also be able to read package-list files produced by Dokka and Javadoc. This would allow Orchid sites to intelligently link to non-Orchid sites.

Example pages that Orchid should be able to read and link to:

• Kotlin stdlib docs: https://kotlinlang.org/api/latest/jvm/stdlib/package-list
• Android reference docs: https://developer.android.com/reference/package-list
• Protobuf: https://developers.google.com/protocol-buffers/docs/reference/java/package-list
• Jackson: https://fasterxml.github.io/jackson-core/javadoc/2.8/package-list

[sjjhsjjh]

Hi, Some things that might contribute to a workaround …

• The kotlindocs plugin has an args option, according to its page in the Orchid Admin screens.

  Arbitrary command line arguments to pass through directly to Dokka.

• Dokka has a -links command line switch by which external documentation links can be specified. See https://github.com/Kotlin/dokka#using-the-command-line

(I tried adding this to my config.yml file:

kotlindoc:
  sourceDirs:
    - '../../../../myproject/src/main/java'
  args:
    - '-links'
    - 'https://developer.android.com/reference/^https://developer.android.com/reference/package-list^^'

It seemed to have no effect, not even an error message. There's no message if I put in rubbish so my guess is that this option isn't there in the code; only in the plugin documentation.
I also tried putting something similar in the afterEvaluate { orchid { ... } } block. That only gets error messages and build failures like:

[INFO] com.google.inject.internal.MessageProcessor: An exception was caught and reported. Message: java.lang.IllegalArgumentException: Unrecognized flag: -links

[cjbrooks12]

Sorry for the confusion here. The args are being passed to Dokka, but there are some flags that may not be relevant anymore with the way Orchid is using Dokka, and passing them in the afterEvaluate { orchid { ... } } block are used for configuring Orchid itself, not Dokka. The Dokka integration is much deeper than simply letting Dokka run normally, and then wrapping the outputs in a layout, so additional care will need to be done to support this.

Basically, I'm having to use Dokka for creating a data model of your Kotlin code, and then letting Orchid render that data model intelligently into templates. -links is used when Dokka resolves references to external pages, but I'm bypassing that part of Dokka and instead resolving those links from the Orchid side, not Dokka. So what needs to happen for this to be supported is not letting Dokka know how to reference external pages (which I'm not letting it do), but instead read those same package-list files from Orchid itself and resolve links properly on the Orchid side.

There are a number of things like this that currently are done very ad-hoc for these code documentation plugins, but I have been doing a ton of work over the past couple months to dramatically improve how these portions of Orchid work. I don't have a timeline for its release yet, but a lot of the problems with the code-doc plugins in their current form will be resolved with these changes, and future problems will be able to be addressed much more easily. Again, sorry for the confusion here, but infrastructural work is being done to support this.