Add kotlin-extension-functions to the documentation

[sdelamo]

No description provided.

[willbuck]

@sdelamo Just wanting to be clear, here; we do have the extension functions documented (in brief) here

Is this meant to get the full dokka documentation (of all extension functions) available as well?

If so, I am nearly done with that, and will create a PR shortly. I will probably want to update the GH action slightly to rename a file that gets generated (unless I am able to chat with the Dokka devs to figure out how to do it via the gradle config; I have requested access to the kotlin slack)

[willbuck]

So it looks like dokka has some kind of likely memory leak that makes actually building the docs a bit tricky.

See this issue for more info / updates: Kotlin/dokka#1405

Also something going on with this issue: Kotlin/dokka#537

So @sdelamo and @jameskleeh we could modify the github action for the release to add --no-parallel --no-daemon -Dorg.gradle.jvmargs="-XX:MaxMetaspaceSize=1g" to the gradlew docs portion, and that should successfully run everything, but I can totally understand why we wouldn't want to do that for every project template, and we can wait on Dokka to figure out the memory issue instead.

Thoughts?

[willbuck]

Root cause seems to be this:

Kotlin/kotlinx.coroutines#2558

dokka crew has said this will be partially fixed with 1.4.30 release of dokka but coroutines fix needed for it to be fully eliminated.

Is there a way we can commit the docs built on my machine to the gh-pages branch and have them stay there through rebuilds until that fix comes?

[ilopmar]

@willbuck you can modify the workflow to adapt it to what this project needs. We have a few workflows modified in some projects like GCP or Kubernetes. The only thing to keep in mind is that we can't automatically merge the "common files updates" PRs, but it's not a big deal.

Regarding the docs. You can generate the docs locally, checkout the gh-pages, copy there the updated version of the docs (keep in mind not only the a.b.x directory but also latest), commit and push the gh-pages branch.

Let me know if you need help or have any additional questions.

[willbuck]

@ilopmar I was thinking of doing the "push straight to gh-pages" but was concerned it would be overwritten by future builds, is that not the case?

I think I would just need to update https://github.com/micronaut-projects/micronaut-kotlin/blob/master/.github/workflows/gradle.yml and hopefully the other files could still merge automatically, is there a particular way I could make future merges as smooth as possible (only add to the end?)

[ilopmar]

@ilopmar I was thinking of doing the "push straight to gh-pages" but was concerned it would be overwritten by future builds, is that not the case?

Yes, it will be overwritten when we do a new release.

I think I would just need to update https://github.com/micronaut-projects/micronaut-kotlin/blob/master/.github/workflows/gradle.yml and hopefully the other files could still merge automatically, is there a particular way I could make future merges as smooth as possible (only add to the end?)

Yeah, that's the workflow you need to modify: https://github.com/micronaut-projects/micronaut-kotlin/blob/master/.github/workflows/gradle.yml#L47

As you are only going to modify the one line it won't be too much complicated to merge the changes in the future. Don't worry :-)

[sdelamo]

can this be closed @willbuck ?

[willbuck]

@sdelamo not quite yet, need to fix the build, didn't get a chance yesterday. Think it's a resource issue

[sdelamo]

@timyates review if this issue should still be open or can be closed.

[timyates]

👍