https://kotlinlang.org logo
Join Slack
Powered by
Do you publish `-javadocs` artifacts to MavenCentr...
# library-development
m
Do you publish 
-javadocs
artifacts to MavenCentral? Is that still used nowadays?
e
IIRC it's required? or was it changed recently?
m
It's required but more and more projects set it to an empty jar which is enough to make validation pass
If no tooling uses it, might as well shave it completely
a
Maven Central requires that the Javadoc JAR exists, but it doesn't check the content. You can ask on the Sonatype JIRA to remove the requirement, and if they're feeling generous they can disable the check for your project. The only usage of a Javadoc JAR that I know about is that websites like https://javadoc.io/ can host it automatically. But for Kotlin projects, I think the Javadoc JAR is pretty useless (and for KMP projects nonsensical). The sources JAR is much more useful.
nod 2
👀 1
j
I just include the html dokka docs in the 
-javadoc
jar. I figure that's at least more useful than an empty one.
m
@Jeff Lockhart this is what I'm doing but this is taking a lot of time I ended up disabling it for Gradle integration tests and 
publishToMavenLocal
. + the setup code is not trivial (we have KMP, Android, JVM, gradle plugins, etc...). At this point I wonder if it's worth maintaining all that code
j
True, dokka is really slow. Probably not a lot of value running it for tests or publishing locally. I actually don't have any manual Gradle configuration setting this up anymore though, since I started using vanniktech's Gradle publish plugin, which does it automatically when using dokka.
👍 1
a
Dokka HTML is really nice on a website, but is packaging it into a JAR going to be used by anyone? I suspect that no one is going to find the Javadoc JAR, unpackage it, run a local webserver (which Dokka requires https://github.com/Kotlin/dokka/issues/1795), vs looking on the website. Am I missing something? :)
m
you could just add a link to the docs inside instead?
I like that!
is packaging it into a JAR going to be used by anyone?
Current plan is to use it for my own needs. CI would download "older" versions from MavenCentral
This puts the "kdoc state" in MavenCentral so anyone can rebuild all the versions without needing a local folder
a
good point - an archive for the docs of all old versions would be useful
j
Those are good points, Adam. Realistically users will view the docs on the website, or an IDE gets them from source. The perfectionist in me just likes the idea of docs in a jar meant for that purpose. I like the file inside at least identifying why it's empty though. Having versioned docs available for users to still access older releases makes sense though. I'm planning to publish versioned API docs on my library's website. I'm just preparing the first release with API changes in the near future, so I'll be working on this soon in fact.
💯 1
👍 1
c
For a long time I was using an empty JAR. Since I switched from Dokka to Dokkatoo, documentation generation time has decreased quite a bit, so now I bundle the module's Dokka output into the Javadoc JAR. My goal is mostly to let javadoc.io work for versioned documentation, since I only host the latest version, and to follow the standards.
👀 1
m
Can javadoc.io work with Dokka HTML? If not, how is Javadoc support for KMP?
Or does javadoc.io just unzip the static files?
c
Yes, it just unzips and hosts whatever is inside it: https://javadoc.io/doc/dev.opensavvy.decouple/polymorphism/0.9.0/index.html
m
Ah, that's pretty cool
Only thing is no "aggregate"/"list all modules" unless you publish one of those
c
m
Dokka has this nice "module documentation"
c
I don't think you can customize it in any way though
👍 1
Well, you can't customize the module list with Dokka either
(unless you go into the HTML templates yourself)
m
no but you can set a small intro paragraph
I could generate the aggregate kdoc in a separate "aggregator module", publish that to maven central and use javadoc.io to host instead of github pages
c
Getting the links to work cross modules would probably not be fun.
😬 1
At least in my situation they don't, since all modules' are built independently.
That's why I also host the latest version as a single big module, in which all cross-references work
👍 1
o
Just out of curiosity: why you don't use 
versioning
plugin to host multi-version Dokka documentation? 🙂
c
Because my CD is stateless, and doesn't have access to the previously built files.
☝️ 1
➕ 1
When I checked, there was no way to give a link to the previously hosted versions, maybe that has changed?
o
Getting the links to work cross modules would probably not be fun.
At least in my situation they don't, since all modules' are built independently.
Theoretically you could setup it via 
externalDocumentationLink
in this case but I haven't tried
c
Theoretically you could setup it via 
externalDocumentationLink
in this case but I haven't tried
That would require hard-coding the links to be to javadoc.io, right? I'm not sure I prefer hard-coding this particular service for anyone who opens the JAR vs not linking at all and letting them figure out they need to open the other JAR too.
m
You can always proxy javadoc.io but then you might as well host yourself 😄
😂 1
> Theoretically you could setup it via 
externalDocumentationLink
in this case but I haven't tried I don't think that can work without some JS/scripting, right? If we're keeping static files as the target, the old docs need to be aware of the "new" docs, which can only happen if everything is built at the same time (i.e. stateful?) edit: or maybe an iframe?
o
Because my CD is stateless, and doesn't have access to the previously built files.
question 1: if you are using github pages, there is possibility to store current version - it should be enough to build next version (as current will include all previous version) question 2: if you are publishing it in 
javadoc.jar
, then you have all previous version built and stored in the most reliable file-storage - Maven Central 🙂 But setup could be not as easy
c
But indeed, for me there are two topics here: • I want to provide a documentation JAR to MavenCentral, because that's a standard, and I like following standards • I also host the multi-module merged dokka output in my CD, because it doesn't have the downsides of javadoc.io (slow to update, only works for published versions, no homepage, doesn't link between modules…). If it was possible, I would prefer for this output to be versioned as well, so it can become the primary source of documentation for my users, however so far it isn't.
o
That would require hard-coding the links to be to javadoc.io, right?
yes, good point, though, if 
javadoc
here is the main use case, so why not? not sure, that a lot of people will open 
javadoc.jar
manually, but I understand
m
you have all previous version built and stored in the most reliable file-storage - Maven Central
FWIW, this is what I'm doing here, downloading the previous versions on demand when building the current version
(means I'm tracking the older versions manually but this is probably for the best, not every minor version is interesting in terms of API)
o
I don't think that can work without some JS/scripting, right?
Not sure why do you need it. 
externalDocumentationLink
will generate links in build time - and as for 
<http://javadoc.io|javadoc.io>
use case, every version will have it's own URL and separate website (inside iframe) So links between modules for single version will be resolved statically Or am I missing something?
c
question 1: if you are using github pages, there is possibility to store current version - it should be enough to build next version (as current will include all previous version)
I'm using GitLab Pages, which is mostly similar: the CD job generates a static website, and GitLab hosts that magically. I do not have a single folder in which old documentation is stored, but I could download each version separately from their version number. I feel like we are a bit going off-topic for this thread, don't hesitate to create another thread in #dokka and @ me so we can continue this discussion 🙂
question 2: if you are publishing it in 
javadoc.jar
, then you have all previous version built and stored in the most reliable file-storage - Maven Central 🙂 But setup could be not as easy
That's true, but the MavenCentral output is not aggregated, each module only has its own documentation, whereas on the main website it's a single output merging everything.
m
Or am I missing something?
Yea, with iframes I think it works 👍. Sorry not a huge HTML expert 😄
c
externalDocumentationLink
will generate links in build time - and as for 
<http://javadoc.io|javadoc.io>
use case, every version will have it's own URL and separate website (inside iframe)
Doesn't it first load the URL to get the package-list, and then only links to what it finds inside it? In this example, all modules would be built in parallel, so none of them have been published yet, and the URL is necessarily incorrect.
👀 1
I'm pretty sure Dokka eagerly warns when the link 404s, though I have no idea what happens after that.
o
I feel like we are a bit going off-topic for this thread, don't hesitate to create another thread in #dokka and @ me so we can continue this discussion
Yeah. I see, there are some things, that are harder than I first thought 🙂 I will try some ways to achieve what you want (now, that I understand the issues) and will come back in coming days I will ping you in #dokka channel after that Thanks!
👍 2
Doesn't it first load the URL to get the package-list, and then only links to what it finds inside it? In this example, all modules would be built in parallel, so none of them have been published yet, and the URL is necessarily incorrect.
Last offtop answer , I promise 🙂 It's possible to provide local path to 
package-list
, so it will be possible to resolve at least links from dependencies (full cross-linking will be not possible I believe) Anyway, it's more a hack, then a proper solution, I understand...
22 Views
Open in Slack
PreviousNext
Powered by