Can anyone recommend a documentation generator for...

# getting-started

[Avi Perl]

Can anyone recommend a documentation generator for Kotlin code, such as sphinx for python?

[Landry Norris]

You can use dokka to generate docs in HTML, GFM, or Jekyll format from your KDocs.

[Casey Brooks]

A long time ago, I built a documentation site generator, Orchid that did integrate with Dokka and other stuff, but it’s now horribly out-of-date and most of its integrations no longer work. I’ve recently started toying with the idea of using Compose to model and generate a static website from arbitrary sources like Dokka output, but I haven’t even created a new repo for this yet.

I mention this to say that there’s not really a great tool now for general-purpose sites that contain Kotlin docs, and I’ve looked and tried to build for good options for years. Most projects I see now basically publish 2 sites: one with Dokka for API documentation, and mkdocs-material for the project wikis

[Casey Brooks]

I will also add that, in most cases, wiki-type documentation will be much more useful for the folks using your library than Dokka-type API docs. Kotlin is statically-typed, so to figure out how to use the library’s APIs, it’s honestly easier to browse source code and use code-completion in IntelliJ, than it is to browse a website. So if you only want to publish 1 docs website, I’d recommend doing mkdocs-material rather than Dokka

[Avi Perl]

Right now the target audience is our internal devs only on a totally internal project. Mostly I think the docs would be consumed in Intellij, but once we are at it, why not set up an auto generated static site that can be visited by folks outside those who have the code? Plus it might encourage better documentation.

[Landry Norris]

If the docs are viewed in IJ, I’d recommend some sort of markdown format, such as GFM. That’s what we do on my team.

[Casey Brooks]

Yeah, if the folks looking at the library have access to the repo, just keeping markdown files in the repo is a good way to manage docs for high-level usage and code snippet examples. And depending on how big the library is, throwing everything into the README is also not a bad way to go. Though do be aware if it’s an Android library, that the default Markdown viewer in Android Studio doesn’t show Markdown previews (though Markdown is very readable even without previews). IntelliJ IDEA does support previews (at least Ultimate, I’m not sure about CE).

If you publish sources jars, then the KDoc comments written in the source code will be available in IJ for free and show up in code completion popups, and when navigating through code, without needing to generate and host a static site.

[Landry Norris]

Community Edition does support Markdown viewing. I use it a lot.