Document project with Dokka/KDocs

[stevenzeck]

Now that this is in a monorepo, it is a good opportunity to document everything from the code and how to use it. Being a Kotlin project, Dokka is the obvious choice.

https://github.com/Kotlin/dokka
https://kotlin.github.io/dokka/1.5.30/

[stevenzeck]

Proof of concept at https://stevenzeck.github.io/kotlin-toolkit/ based on https://github.com/stevenzeck/kotlin-toolkit/tree/gh-pages. This is a bare minimum HTML implementation with no customization. I've seen quite a few projects using mkdocs as opposed to HTML, including Dokka itself.

[mickael-menu]

Yes that would definitely be valuable. Ideally it's something that could be generated automatically from a GitHub Actions workflow when something is merged on develop.

[stevenzeck]

I think I've taken this as far as I can go. It needs content and theming.

A different proof of concept is available at the same URL: https://stevenzeck.github.io/kotlin-toolkit/. This one uses both Dokka and MkDocs. I prefer Dokka's HTML layout of API docs over MkDocs generated HTML from Dokka Markdown, but I think this gives us much more flexibility and ease of use. I can't find an easy way of providing our own files for Dokka HTML.
For reference, another project that uses Dokka and MkDocs is https://square.github.io/workflow/.

There are plenty of oddities I haven't figured out such as random ~ characters all over, several broken links (though these were present on Dokka HTML too). The only way I could fix this was by skipping deprecated code to be documented. The GitHub workflow is also not 100% correct, as I have to delete the gh-pages branch manually when I want to deploy it fresh because of this error: https://github.com/stevenzeck/kotlin-toolkit/runs/3773391231?check_suite_focus=true. The only way I could fix that was by adding --force to the gh-deploy command. I'm sure there are plenty of other things that can be done to optimize it, like only update documentation when it has actually changed.

If you want to try it yourself locally (this is on a Mac)...

Dokka HTML

1. Checkout the dokka branch
2. Run the dokkaHtmlMultiModule gradle task
3. When it completes, look in the root docs folder for an index.html file.

Note that the search and side navigation don't work locally, they require a server. Push to a branch and use GitHub Pages if you want to try that out.

Dokka Markdown/MkDocs

1. Install MkDocs (pip install mkdocs or python3 -m pip install mkdocs)
2. Install MkDocs material (python3 -m pip install mkdocs-material)
3. Checkout the dokka branch
4. If necessary, delete anything in the docs folder that was previously auto-generated
5. Run the dokkaGfmMultiModule gradle task
6. Run python3 -m mkdocs serve

It will take a minute or two, but eventually it will give you the local URL to view it. I also have a cleanDocs gradle task that deletes the auto-generated readium folder and index.md files to re-run the process. You'll also want lsof -ti tcp:8000 -sTCP:LISTEN | xargs kill so it can reuse the address.

[mickael-menu]

The documentation from Square's Workflow is interesting as it merges the two Swift and Kotlin API references: https://square.github.io/workflow/#using-workflows-in-your-project

[mickael-menu]

This is now implemented in #19 and the result can be found at https://readium.org/kotlin-toolkit/latest

There are a few rendering issues and Mkdocs warnings we can iterate on, but that's already a great step to a more accessible toolkit. Thanks @stevenzeck!