Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Implement Dokka API reference #2251

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Conversation

aSemy
Copy link
Contributor

@aSemy aSemy commented May 9, 2024

This PR updates the build config to generates Dokka HTML API code reference for all subprojects.

To generate the API docs:

  1. Run ./gradlew :docs:dokkaGen
  2. Open docs/build/dokka/html/index.html in a browser.

Part of #2228.

The next step is publishing the API reference to a website (e.g. GitHub Pages).

Screenshots

Here are some example screenshots.

  • The home page shows a list of all modules, each with a brief description (from the README.md in each subproject)

    image
  • When viewing a module, all content from the module's README.md is available

    image
  • Code and KDoc are easily viewable and searchable
    image

Summary

  • Update subproject READMEs to use as Dokka Module files (add # Module header)
  • Generate aggregated Dokka HTML in the :docs subproject
  • Remove 'archived' from headings - Dokka needs the heading to match the module name exactly. Instead, use admonitions. But... Dokka doesn't support them. So instead, find/replace the admonitions with emojis.

Reasons for using Dokkatoo over the existing Dokka Gradle Plugin.

  • Dokkatoo compatible with the Gradle API and follows best practices, resulting in better performance. DGP is not compatible, resulting in worse build performance and more Gradle warnings.
  • kotlin-wrappers has a :docs subproject. It makes sense to aggregate the API docs into this subproject. DGP cannot create an aggregated HTML doc into a subproject, while Dokkatoo can.

@aSemy aSemy force-pushed the feat/dokka branch 3 times, most recently from bcf8e47 to 9db4177 Compare May 9, 2024 12:55
- Generate Dokka code reference for all subprojects
- Update subproject READMEs to use as Dokka Module files (add `# Module` header)
- Generate aggregated Dokka HTML in the `:docs` subproject
- Remove 'archived' from headings - Dokka needs the heading to match the module name _exactly_. Instead, use admonitions. But... Dokka doesn't support them. So instead, find/replace the admonitions with emojis
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant