[WIP] Dokka support!

[RedstoneWizard08]

This adds support for Dokka like Javadoc!

Closes:

• Support for Dokka in the JavaDoc integration #2117

Improvements:

• Dokka support
• Makes release builds faster (Java/Kotlin doesn't need to be recompiled on arm, it can be done on x86 in CI)

A few things, though:

• Help wanted! I have no idea how to make Dokka work with the access control properly, and currently I have a list of exclusions and this is very bad. Dokka requires a lot of fetch and that doesn't work with the current access control system. Please help!
• This is NOT ready for production!
• I accidentally changed the package version to 3.5.13... it was just for publishing to Docker Hub so I could use it.
• I need to revert the changes to publishing before release!
• There are still a few issues with the implementation - for some reason members don't render, and I have no idea why. It might be a problem with my own Dokka config, but I'm not sure. The HTML looks correct.

[RedstoneWizard08]

P.S. Yes, I reviewed my own code. I've found it helps me.

[dzikoysk]

Hey, thanks for for PR! Some quick feedback regarding the ticket for Dokka:

1. I think it should be developed as external plugin first, just like javadocs in the past. Once we confirm it works as expected & we'll see a demand on this, it can be merged to the module in the future.
2. The release build was intentionally a part of arm build, because we're also running tests there to make sure everything works as expected. Thanks to that, we were able to e.g. notice a problem with SQLite that was unable to correctly create db file.
3. Dealing with these docs sites is a bit tricky, because we need to run them in sandbox to prevent malicious js content. Maybe it could be a bit easier in 4.x, because we'll move to regular http sessions. Maybe we should even encourage people to host docs on separate subdomains if possible.

Not sure about the rest, I never used Dokka on my own :<

[RedstoneWizard08]

Okay! I'll move it to a plugin, and maybe I'll find a way to run tests after build (to save time). Otherwise, I'll revert the ARM changes. Thanks for the feedback!

Edit: A plugin might make it easier for me, since I'm deploying it on a private server that's separate from the VM I'm using to develop it, so the build time should be faster for that. xD

[RedstoneWizard08]

Also, yeah, dealing with JS is tricky. I might have to end up making a custom frontend for Dokka that reads its data and renders it. Dokka uses a lot of manifests and json so it shouldn't be too hard.

[pauliesnug]

Dealing with these docs sites is a bit tricky, because we need to run them in sandbox to prevent malicious js content. Maybe it could be a bit easier in 4.x, because we'll move to regular http sessions. Maybe we should even encourage people to host docs on separate subdomains if possible.

Dokka also allows for non-default JS to be loaded at buildtime in the jar, so that might cause issues (but I do think it is important to support, Dokka's whole thing is being super extendible and pretty)

[pauliesnug]

Do we need a custom Dokka frontend and prism styles though? That should be handled by the user with the aforementioned custom CSS/JS in the Dokka jar individually. This feels like some things in this PR are specific to your own use but I'm not sure

[RedstoneWizard08]

Do we need a custom Dokka frontend and prism styles though? That should be handled by the user with the aforementioned custom CSS/JS in the Dokka jar individually. This feels like some things in this PR are specific to your own use but I'm not sure

I'd want to do this, but when I try to load a dokka site, none of the members or classes load when looking at a page. I can't see any issues even in the console. It confuses me. If I find a solution, I'll remove the custom frontend entirely.

[RedstoneWizard08]

I'm also kinda clueless here :p I'm just throwing stuff at the wall and seeing what works

[RedstoneWizard08]

Ok scratch all of that, I found the error.

[RedstoneWizard08]

Hey @dzikoysk I fixed the issues, now I just need to move it into the plugin. How do I do this? I just copy and pasted the directory and references, so I don't actually know how to make a plugin. Is there some documentation I am missing?

[RedstoneWizard08]

Also the error was just a content security policy thing. :p

[RedstoneWizard08]

Also for some reason, there are a bunch of "changes" that I had nothing to do with - I think VS Code is just fricking around with line endings.

[RedstoneWizard08]

Also it still doesn't work outside of the Raw docs option.

Edit: Nevermind, it totally does! 🎉
Edit 2: Also confirmed that Javadocs still work.

[pauliesnug]

Also it still doesn't work outside of the Raw docs option.

Edit: Nevermind, it totally does! 🎉 Edit 2: Also confirmed that Javadocs still work.

This is amazing, thank you so much! 🎉
I wonder if security is still a concern... I'm not sure how sanitization would even work here though. Maybe since its a plugin, sanitization wouldn't matter, since it's opt-in, which means users are accepting the risk of a bad actor uploading a dokka jar with unsafe javascript?

[pauliesnug]

Hey @dzikoysk I fixed the issues, now I just need to move it into the plugin. How do I do this? I just copy and pasted the directory and references, so I don't actually know how to make a plugin. Is there some documentation I am missing?

The majority of your code uses the standard plugin API as far as I know. You can look at something like swagger-plugin and just create a new entry for ./reposilite-plugins/dokka-plugin with a similar build.gradle.kts, and then try to copy the existing code in the plugin facade structure.

I'm not sure how frontend plugins work though...

[RedstoneWizard08]

Hey @dzikoysk I fixed the issues, now I just need to move it into the plugin. How do I do this? I just copy and pasted the directory and references, so I don't actually know how to make a plugin. Is there some documentation I am missing?

The majority of your code uses the standard plugin API as far as I know. You can look at something like swagger-plugin and just create a new entry for ./reposilite-plugins/dokka-plugin with a similar build.gradle.kts, and then try to copy the existing code in the plugin facade structure.

I'm not sure how frontend plugins work though...

Ok. I got rid of the frontend too, so it shouldn't matter there.

[RedstoneWizard08]

Hi sorry I've been silent on this for a while, I've been doing other stuff and... finals. Hopefully I'll have this done within the next week or so.

[dzikoysk]

No rush, take your time :)

[solonovamax]

I'm gonna be honest, I use dokka a decent amount and I have basically never seen an *-dokka.jar archive..?

Are those files actually used in practice? Because afaik, you'll generally publish dokka documentation in a *-javadoc.jar archive.
Also, since all the code for the dokka shit seems to be literally just identical to the javadoc preview code, imo it should just use the same class.

As for the dom exceptions, I've figured out that you can remove the sandbox attribute and instead use the new credentialless attribute for the iframe. However, do note that this is currently not supported in the latest version of firefox.
Until it is supported, from what I can tell there is no safe way to allow local storage to be used.
However, one thing that perhaps can be done is to inject some js into the iframe (possibly: inject it directly into the html file?) that mocks the local storage, like this library here: https://github.com/mattiaocchiuto/iframe-localstorage, creating an ephemeral local storage that doesn't actually save anything.