Skip to content

Commit

Permalink
Dokkatoo docs update (#187)
Browse files Browse the repository at this point in the history
* add Dokka HTML module info (finally!)

* update attributes in buildsrc convention Configurations

* add Dokkatoo example for versioning-multimodule

* add Writerside docs

* add kotlin-as-java Dokkatoo example

* generate dokka into a nested /kdoc/ directory for GitHub Pages

* hide previousDocVersions from GitHub stats/diffs

* Revert GitHub Action pages Upload path change (path was changed in the build script instead)

* update example projects docs, and minor fixes

* move writerside docs up one level

* GitHub pages tweaks for Writerside

* update workflow for writerside

* move Writerside env vars to relevant task
  • Loading branch information
aSemy authored Mar 10, 2024
1 parent 19f4412 commit b78fd6a
Show file tree
Hide file tree
Showing 204 changed files with 12,497 additions and 26 deletions.
10 changes: 6 additions & 4 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,12 @@ gradlew text eol=lf
*.svg text

# Exclude external libs from GitHub language stats https://github.com/github/linguist/blob/v7.24.1/docs/overrides.md
examples/** linguist-documentation
examples/*/dokka linguist-vendored
modules/dokkatoo-plugin-integration-tests/projects/**dokka/ linguist-vendored
modules/dokkatoo-plugin-integration-tests/projects/**dokkatoo/ linguist-documentation
examples/** linguist-documentation
examples/*/dokka linguist-vendored
examples/versioning-multimodule-example/dokka/previousDocVersions linguist-generated
examples/versioning-multimodule-example/dokkatoo/previousDocVersions linguist-generated
modules/dokkatoo-plugin-integration-tests/projects/**dokka/ linguist-vendored
modules/dokkatoo-plugin-integration-tests/projects/**dokkatoo/ linguist-documentation

# Exclude files from exporting

Expand Down
43 changes: 38 additions & 5 deletions .github/workflows/run_publish_site.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ concurrency:

jobs:

build:
build-dokka:
runs-on: ubuntu-latest
steps:
- name: Checkout the repo
Expand All @@ -40,20 +40,52 @@ jobs:
distribution: temurin
java-version: 11

- uses: gradle/gradle-build-action@v3
- name: dokkatooGenerate
uses: gradle/gradle-build-action@v3
with:
gradle-home-cache-cleanup: true
# write build cache on 'main' and 'release' branches, or tags (default is 'main' only)
cache-read-only: ${{ github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/heads/release') && !startsWith(github.ref, 'refs/tags/') }}
arguments: |
:modules:docs:dokkatooGenerate
- uses: actions/upload-pages-artifact@v3
- name: Upload Dokka to Pages
uses: actions/upload-pages-artifact@v3
with:
path: ./modules/docs/build/dokka/html
path: ./modules/docs/build/dokka/html/


build-writerside:
runs-on: ubuntu-latest
env:
WRITERSIDE_INSTANCE: "modules/docs/d"
WRITERSIDE_DOC_ZIP: "webHelpD2-all.zip"
steps:
- name: Build Writerside docs
uses: JetBrains/writerside-github-action@v4
with:
instance: ${{ env.WRITERSIDE_INSTANCE }}
artifact: ${{ env.WRITERSIDE_DOC_ZIP }}
docker-version: "233.14389"

- name: Writerside check
uses: JetBrains/writerside-checker-action@v1
with:
instance: ${{ env.WRITERSIDE_INSTANCE }}

- name: Unpack Writerside zip
run: unzip -O UTF-8 -qq '${{ env.WS_ALL_ZIP }}' -d writerside-dir

- name: Upload Writerside to Pages
uses: actions/upload-pages-artifact@v3
with:
path: ./writerside-dir/


deploy:
needs: build
needs:
- build-dokka
- build-writerside
runs-on: ubuntu-latest
permissions:
pages: write # to deploy to Pages
Expand All @@ -62,6 +94,7 @@ jobs:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:

- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ Dokkatoo has a number of improvements over the existing Dokka Gradle Plugin:
* Compatible with [Gradle Build Cache](https://docs.gradle.org/current/userguide/build_cache.html)
* Compatible with
[Gradle Configuration Cache](https://docs.gradle.org/current/userguide/configuration_cache.html)
* Safe cross-project sharing and aggregation
* Parallel execution
* Follows Gradle best practices for plugin development, for a more stable experience
* Faster, parallel execution


### Status
Expand Down Expand Up @@ -80,7 +80,7 @@ and
2. Run the generation task

```shell
./gradlew dokkatooGenerate
./gradlew :dokkatooGenerate
```

3. View the results in `./build/dokka/`
Expand Down
2 changes: 2 additions & 0 deletions build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ idea {
"build",
"gradle/wrapper",
"ANDROID_SDK",
"examples/versioning-multimodule-example/dokkatoo/previousDocVersions",
"examples/versioning-multimodule-example/dokka/previousDocVersions",
)
addAll(
projectDir.walk().filter { file ->
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import buildsrc.utils.consumable
import buildsrc.utils.declarable
import buildsrc.utils.dropDirectories
import buildsrc.utils.resolvable
import org.gradle.api.attributes.Category.CATEGORY_ATTRIBUTE
import org.gradle.api.attributes.Usage.USAGE_ATTRIBUTE
import org.gradle.kotlin.dsl.support.serviceOf

Expand All @@ -17,17 +18,16 @@ val dsdExt: DokkaSourceDownloaderSettings = extensions.create<DokkaSourceDownloa
)

val kotlinDokkaSource: Configuration by configurations.creating {
description = "Source code for https://github.com/Kotlin/dokka/"
declarable()
attributes {
attribute(USAGE_ATTRIBUTE, objects.named("externals-dokka-src"))
}
}

val kotlinDokkaSourceResolvable: Configuration by configurations.creating {
resolvable()
extendsFrom(kotlinDokkaSource)
attributes {
attribute(USAGE_ATTRIBUTE, objects.named("externals-dokka-src"))
attribute(CATEGORY_ATTRIBUTE, objects.named("externals-dokka-src"))
}
}

Expand All @@ -36,6 +36,7 @@ val kotlinDokkaSourceConsumable: Configuration by configurations.creating {
extendsFrom(kotlinDokkaSource)
attributes {
attribute(USAGE_ATTRIBUTE, objects.named("externals-dokka-src"))
attribute(CATEGORY_ATTRIBUTE, objects.named("externals-dokka-src"))
}
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package buildsrc.conventions
import buildsrc.utils.consumable
import buildsrc.utils.declarable
import buildsrc.utils.resolvable
import org.gradle.api.attributes.Category.CATEGORY_ATTRIBUTE

plugins {
id("buildsrc.conventions.base")
Expand All @@ -19,17 +20,22 @@ dependencies.attributesSchema {

val exampleProjects: Configuration by configurations.creating {
declarable()
attributes { attribute(exampleProjectsAttribute, "dokka") }
}

val exampleProjectsResolvable: Configuration by configurations.creating {
resolvable()
extendsFrom(exampleProjects)
attributes { attribute(exampleProjectsAttribute, "dokka") }
attributes {
attribute(exampleProjectsAttribute, "dokka")
attribute(CATEGORY_ATTRIBUTE, objects.named("dokkatoo-example-projects"))
}
}

val exampleProjectsConsumable: Configuration by configurations.creating {
consumable()
extendsFrom(exampleProjects)
attributes { attribute(exampleProjectsAttribute, "dokka") }
attributes {
attribute(exampleProjectsAttribute, "dokka")
attribute(CATEGORY_ATTRIBUTE, objects.named("dokkatoo-example-projects"))
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ package buildsrc.conventions

import buildsrc.settings.MavenPublishTestSettings
import buildsrc.utils.*
import org.gradle.api.attributes.Category.CATEGORY_ATTRIBUTE
import org.gradle.api.attributes.Usage.USAGE_ATTRIBUTE


/** Utility for publishing a project to a local Maven directory for use in integration tests. */
Expand Down Expand Up @@ -68,16 +70,15 @@ plugins.withType<MavenPublishPlugin>().all {

val testMavenPublication: Configuration by configurations.creating {
declarable()
attributes {
attribute(MavenPublishTestSettings.attribute, "testMavenRepo")
}
}

val testMavenPublicationResolvable: Configuration by configurations.creating {
resolvable()
extendsFrom(testMavenPublication)
attributes {
attribute(MavenPublishTestSettings.attribute, "testMavenRepo")
attribute(USAGE_ATTRIBUTE, objects.named("maven-publish-test"))
attribute(CATEGORY_ATTRIBUTE, objects.named("maven-publish-test"))
}
outgoing {
artifact(mavenPublishTestExtension.testMavenRepo) {
Expand All @@ -91,6 +92,8 @@ val testMavenPublicationConsumable: Configuration by configurations.creating {
extendsFrom(testMavenPublication)
attributes {
attribute(MavenPublishTestSettings.attribute, "testMavenRepo")
attribute(USAGE_ATTRIBUTE, objects.named("maven-publish-test"))
attribute(CATEGORY_ATTRIBUTE, objects.named("maven-publish-test"))
}
outgoing {
artifact(mavenPublishTestExtension.testMavenRepo) {
Expand Down
2 changes: 1 addition & 1 deletion buildSrc/src/main/kotlin/buildsrc/utils/gradle.kt
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ import org.gradle.kotlin.dsl.*
* ```
*/
fun Configuration.consumable(
visible: Boolean = true
visible: Boolean = false
) {
isVisible = visible
isCanBeResolved = false
Expand Down
2 changes: 0 additions & 2 deletions examples/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,5 @@ gradlew.bat
gradlew
gradle.properties

versioning-multimodule-example/dokka/previousDocVersions

# these are test projects, so don't commit the lock file
**/kotlin-js-store/yarn.lock
2 changes: 1 addition & 1 deletion examples/gradle-example/dokkatoo/build.gradle.kts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
plugins {
kotlin("jvm") version "1.9.10"
kotlin("jvm") version "1.9.23"
id("dev.adamko.dokkatoo") version "2.3.0-SNAPSHOT"
}

Expand Down
16 changes: 16 additions & 0 deletions examples/kotlin-as-java-example/dokkatoo/build.gradle.kts
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
plugins {
kotlin("jvm") version "1.9.23"
id("dev.adamko.dokkatoo") version "2.3.0-SNAPSHOT"
}

dependencies {
testImplementation(kotlin("test-junit"))

// Will apply the plugin only to the `:dokkaHtml` task
// (Dokkatoo will automatically add the version)
dokkatooPluginHtml("org.jetbrains.dokka:kotlin-as-java-plugin")

// Will apply the plugin only to the `:dokkaGfm` task
// (Dokkatoo will automatically add the version)
dokkatooPluginGfm("org.jetbrains.dokka:kotlin-as-java-plugin")
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
package demo

/**
* This class supports greeting people by name.
*
* @property name The name of the person to be greeted.
*/
class Greeter(val name: String) {

/**
* Prints the greeting to the standard output.
*/
fun greet() {
println("Hello $name!")
}
}

fun main(args: Array<String>) {
Greeter(args[0]).greet()
}
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@ plugins {
}

dependencies {
implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.10")
implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.23")
implementation("dev.adamko.dokkatoo:dokkatoo-plugin:2.3.0-SNAPSHOT")
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
<!doctype html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1" charset="UTF-8">
<title>ChildProjectAClass</title>
<link href="../../../images/logo-icon.svg" rel="icon" type="image/svg"><script>var pathToRoot = "../../../";</script> <script>const storage = localStorage.getItem("dokka-dark-mode")
if (storage == null) {
const osDarkSchemePreferred = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
if (osDarkSchemePreferred === true) {
document.getElementsByTagName("html")[0].classList.add("theme-dark")
}
} else {
const savedDarkMode = JSON.parse(storage)
if(savedDarkMode === true) {
document.getElementsByTagName("html")[0].classList.add("theme-dark")
}
}
</script>
<script type="text/javascript" src="../../../scripts/sourceset_dependencies.js" async></script>
<link href="../../../styles/style.css" rel="Stylesheet">
<link href="../../../styles/jetbrains-mono.css" rel="Stylesheet">
<link href="../../../styles/main.css" rel="Stylesheet">
<link href="../../../styles/prism.css" rel="Stylesheet">
<link href="../../../styles/logo-styles.css" rel="Stylesheet">
<script type="text/javascript" src="../../../scripts/clipboard.js" async></script>
<script type="text/javascript" src="../../../scripts/navigation-loader.js" async></script>
<script type="text/javascript" src="../../../scripts/platform-content-handler.js" async></script>
<script type="text/javascript" src="../../../scripts/main.js" defer></script>
<script type="text/javascript" src="../../../scripts/prism.js" async></script>
<script type="text/javascript" src="../../../scripts/symbol-parameters-wrapper_deferred.js" defer></script>
<link href="../../../styles/multimodule.css" rel="Stylesheet"></head>
<body>
<div class="navigation-wrapper" id="navigation-wrapper">
<div id="leftToggler"><span class="icon-toggler"></span></div>
<div class="library-name">
<a href="../../../index.html">
<span>parentProject</span> </a> </div>
<div>
<dokka-template-command data="{&quot;@class&quot;:&quot;org.jetbrains.dokka.base.templating.ReplaceVersionsCommand&quot;,&quot;location&quot;:&quot;demo/-child-project-a-class/-child-project-a-class.html&quot;}">0.9</dokka-template-command> </div>
<div class="pull-right d-flex">
<button id="theme-toggle-button"><span id="theme-toggle"></span></button>
<div id="searchBar"></div>
</div>
</div>
<div id="container">
<div id="leftColumn">
<div id="sideMenu"></div>
</div>
<div id="main">
<div class="main-content" id="content" pageids="childProjectA::demo/ChildProjectAClass/ChildProjectAClass/#/PointingToDeclaration//-638285599">
<div class="breadcrumbs"><a href="../../index.html">childProjectA</a><span class="delimiter">/</span><a href="../index.html">demo</a><span class="delimiter">/</span><a href="index.html">ChildProjectAClass</a><span class="delimiter">/</span><span class="current">ChildProjectAClass</span></div>
<div class="cover ">
<h1 class="cover"><span>Child</span><wbr><span>Project</span><wbr><span><span>AClass</span></span></h1>
</div>
<div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":parentProject:childProjectA:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword"></span><span class="token keyword">fun </span><a href="-child-project-a-class.html"><span class="token function">ChildProjectAClass</span></a><span class="token punctuation">(</span><span class="token punctuation">)</span></div></div></div>
</div>
<div class="footer">
<span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>© 2022 Copyright</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span>
</div>
</div>
</div>

</body></html>

Loading

0 comments on commit b78fd6a

Please sign in to comment.