diff --git a/.github/workflows/gh-pages-deploy-dev-docs.yml b/.github/workflows/gh-pages-deploy-dev-docs.yml index ce1caf3558..8516a72138 100644 --- a/.github/workflows/gh-pages-deploy-dev-docs.yml +++ b/.github/workflows/gh-pages-deploy-dev-docs.yml @@ -30,7 +30,7 @@ jobs: run: echo "DOKKA_VERSION=`./gradlew :properties | grep '^version:.*' | cut -d ' ' -f 2`" >> $GITHUB_ENV working-directory: ./dokka - name: Build docs - run: ./gradlew mkdocsBuild -Pdokka_version=$DOKKA_VERSION --info + run: ./gradlew buildMkDocsSite -Pdokka_version=$DOKKA_VERSION --info working-directory: ./dokka - name: Deploy uses: peaceiris/actions-gh-pages@v3 diff --git a/build-logic/src/main/kotlin/dokkabuild.dev-maven-publish.gradle.kts b/build-logic/src/main/kotlin/dokkabuild.dev-maven-publish.gradle.kts index 92e731d5ec..05600c55d7 100644 --- a/build-logic/src/main/kotlin/dokkabuild.dev-maven-publish.gradle.kts +++ b/build-logic/src/main/kotlin/dokkabuild.dev-maven-publish.gradle.kts @@ -3,9 +3,9 @@ */ import dokkabuild.DevMavenPublishExtension import dokkabuild.DevMavenPublishExtension.Companion.DEV_MAVEN_PUBLISH_EXTENSION_NAME -import dokkabuild.internal.consumable -import dokkabuild.internal.declarable -import dokkabuild.internal.resolvable +import dokkabuild.utils.consumable +import dokkabuild.utils.declarable +import dokkabuild.utils.resolvable import org.gradle.kotlin.dsl.support.uppercaseFirstChar /** diff --git a/build-logic/src/main/kotlin/dokkabuild/internal/gradleUtils.kt b/build-logic/src/main/kotlin/dokkabuild/internal/gradleUtils.kt deleted file mode 100644 index 6343908e69..0000000000 --- a/build-logic/src/main/kotlin/dokkabuild/internal/gradleUtils.kt +++ /dev/null @@ -1,61 +0,0 @@ -/* - * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. - */ - -package dokkabuild.internal - -import org.gradle.api.artifacts.Configuration - -/** - * Mark this [Configuration] as one that will be consumed by other subprojects. - * - * ``` - * isCanBeResolved = false - * isCanBeConsumed = true - * isCanBeDeclared = false - * ``` - */ -fun Configuration.consumable( - visible: Boolean = false -) { - isVisible = visible - isCanBeResolved = false - isCanBeConsumed = true - isCanBeDeclared = false -} - -/** - * Mark this [Configuration] as one that will consume artifacts from other subprojects (also known as 'resolving') - * - * ``` - * isCanBeResolved = true - * isCanBeConsumed = false - * isCanBeDeclared = false - * ``` - */ -fun Configuration.resolvable( - visible: Boolean = false -) { - isVisible = visible - isCanBeResolved = true - isCanBeConsumed = false - isCanBeDeclared = false -} - -/** - * Mark this [Configuration] as one that will be used to declare dependencies. - * - * ``` - * isCanBeResolved = false - * isCanBeConsumed = false - * isCanBeDeclared = true - * ``` - */ -fun Configuration.declarable( - visible: Boolean = false -) { - isVisible = visible - isCanBeResolved = false - isCanBeConsumed = false - isCanBeDeclared = true -} diff --git a/docs-developer/README.md b/docs-developer/README.md index d415dbf758..4b048b2465 100644 --- a/docs-developer/README.md +++ b/docs-developer/README.md @@ -1,16 +1,16 @@ # Developer documentation -This module contains developer documentation which is published to GitHub pages: +This module contains developer documentation which is published to GitHub pages: [kotlin.github.io/dokka](https://kotlin.github.io/dokka/). It is built using the [gradle-mkdocs-plugin](https://github.com/xvik/gradle-mkdocs-plugin). ## Building -You can build the documentation locally: +You can build the documentation: ```Bash -./gradlew :docs-developer:mkdocsBuild +./gradlew :docs-developer:mkDocsBuild ``` The output directory is `build/mkdocs`. @@ -23,18 +23,22 @@ Alternatively, you can use Docker: docker run --rm -it -p 8000:8000 -v ./docs-developer/src/doc:/docs squidfunk/mkdocs-material ``` -This will build the docs and start a web server under [localhost:8000/Kotlin/dokka](http://localhost:8000/Kotlin/dokka/). +This will build the docs and start a web server under +[localhost:8000/Kotlin/dokka](http://localhost:8000/Kotlin/dokka/). -### Livereload server +### Live-reload server -Alternatively, you can run a livereload server that automatically rebuilds documentation on every change: +If you are using IntelliJ then a link to the docs will be logged in the console: -```Bash -./gradlew :docs-developer:mkdocsServe +```text +Dokka Developer Docs: http://localhost:63342/dokka/docs-developer/build/mkdocs/index.html ``` -By default, it is run under [localhost:3001](http://localhost:3001/), but you can change it in -[mkdocs.yml](src/doc/mkdocs.yml) by setting the `dev_addr` option. +To automatically rebuild the docs, run in continuous mode: + +```Bash +./gradlew :docs-developer:mkDocsBuild --continuous --quiet +``` ## Publishing diff --git a/docs-developer/build.gradle.kts b/docs-developer/build.gradle.kts index 908b14c725..2bd9c82e7b 100644 --- a/docs-developer/build.gradle.kts +++ b/docs-developer/build.gradle.kts @@ -1,16 +1,179 @@ /* * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. */ +import com.pswidersk.gradle.python.VenvTask +import org.apache.tools.ant.filters.ReplaceTokens +import org.gradle.api.tasks.PathSensitivity.RELATIVE +import org.jetbrains.kotlin.util.parseSpaceSeparatedArgs plugins { - id("ru.vyarus.mkdocs") version "2.4.0" + id("com.pswidersk.python-plugin") version "2.4.0" } -if (project.version.toString().endsWith("-SNAPSHOT")) { - // Do not generate the root index.html file with the redirect - // to a snapshot version, otherwise GitHub Pages-based documentation - // will always lead to the non-yet-released documentation. - // For more details, see https://github.com/Kotlin/dokka/issues/2869. - // For configuration details, see https://xvik.github.io/gradle-mkdocs-plugin/3.0.0/examples/#simple-multi-version. - mkdocs.publish.rootRedirect = false +val dokkaVersion = provider { project.version.toString() } +val isDokkaSnapshotVersion = dokkaVersion.map { it.endsWith("-SNAPSHOT") } + +/** Directory containing generated docs. */ +val currentMkDocsDir: Provider = layout.buildDirectory.dir("mkdocs-current") + +/** + * Directory containing a fully built MkDocs site, ready for upload to GitHub Pages. + * + * The [currentMkDocsDir] must be placed in a [dokkaVersion] subdirectory. + * + * ```. + * └── build/ + * └── mkdocs/ + * └── 1.2.3-SNAPSHOT/ + * └── + * ``` + * + * If [dokkaVersion] is a release version (non-SNAPSHOT) then the dir must contain an index.html + * that redirects to the current version. + * + * ``` + * └── build/ + * ├── mkdocs/ + * │ └── 1.2.3/ + * │ └── + * └── index.html (redirects to `1.2.3/index.html`) + * ``` + */ +val mkDocsSiteDir: Provider = layout.buildDirectory.dir("mkdocs") + +val mkDocsSetup: TaskProvider by tasks.registering(VenvTask::class) { + description = "Install required Python libraries" + group = project.name + venvExec = "pip" + args = parseSpaceSeparatedArgs("install -r requirements.txt") + + inputs.file("requirements.txt") + .withPropertyName("requirements.txt") + .withPathSensitivity(RELATIVE) + .normalizeLineEndings() +} + +val pipPrintRequirements by tasks.registering(VenvTask::class) { + description = "Log the current requirements (useful util for manually updating dependencies & requirements.txt)" + group = project.name + venvExec = "pip" + args = parseSpaceSeparatedArgs("freeze") +} + +val mkDocsBuild: TaskProvider by tasks.registering(VenvTask::class) { + description = "Compile Dokka Developer Documentation site using MkDocs" + group = project.name + + dependsOn(mkDocsSetup) + finalizedBy(logMkDocsLink) + + venvExec = "mkdocs" + args = parseSpaceSeparatedArgs("build") + + inputs.dir("docs") + .withPropertyName("docs") + .withPathSensitivity(RELATIVE) + .normalizeLineEndings() + + inputs.file("mkdocs.yml") + .withPropertyName("mkdocs.yml") + .withPathSensitivity(RELATIVE) + .normalizeLineEndings() + + // output directory is also specified in mkdocs.yml as `site_dir` + outputs.dir(currentMkDocsDir) + .withPropertyName("mkDocsOutputDir") + + outputs.cacheIf("always cache - task has defined output directory") { true } +} + +val generateMkDocsSiteIndexHtml by tasks.registering(Sync::class) { + description = "Generate the root index.html" + group = project.name + + val dokkaVersion = dokkaVersion + inputs.property("dokkaVersion", dokkaVersion) + + val indexHtml = layout.projectDirectory.file("index.html") + inputs.file(indexHtml) + .withPropertyName("indexHtml") + .withPathSensitivity(RELATIVE) + .normalizeLineEndings() + + from(indexHtml) + + filter("tokens" to mapOf("dokkaVersion" to dokkaVersion.get())) + + into(temporaryDir) +} + + +val buildMkDocsSite by tasks.registering(Sync::class) { + description = "Generate a complete MkDocs site, with versioned subdirectories" + group = project.name + + val dokkaVersion = dokkaVersion + inputs.property("dokkaVersion", dokkaVersion) + +// only generate a root index.html on non-snapshot versions + if (!isDokkaSnapshotVersion.get()) { + from(generateMkDocsSiteIndexHtml) + } + from(mkDocsBuild) { + eachFile { + relativePath = relativePath.prepend(dokkaVersion.get()) + } + } + + includeEmptyDirs = false + + into(mkDocsSiteDir) +} + +val logMkDocsLink: TaskProvider by tasks.registering { + description = "Prints a link to the generated docs" + group = project.name + + dependsOn(buildMkDocsSite) + doNotTrackState("this task performs no work and should always log the link") + + // redefine currentMkDocsDir for config-cache compliance + val mkDocsDir = buildMkDocsSite.map { it.destinationDir } + + val ideaActive = System.getProperty("idea.active").toBoolean() + + val dokkaProjectDir = project.rootDir.parentFile + + val dokkaVersion = dokkaVersion + val isDokkaSnapshotVersion = isDokkaSnapshotVersion + + doLast { + val indexHtml = if (isDokkaSnapshotVersion.get()) { + mkDocsDir.get().resolve("${dokkaVersion.get()}/index.html") + } else { + mkDocsDir.get().resolve("index.html") + } + + val link: String = + if (ideaActive) { + // The built-in IntelliJ server requires a specific path to index.html: + // a _relative_ path starting with the project's directory (dokka) + val relativeOutputPath = indexHtml.relativeTo(dokkaProjectDir).invariantSeparatorsPath + "http://localhost:63342/$relativeOutputPath" + } else { + indexHtml.toURI().toString() + } + + logger.quiet( + """ + | + |*************************************************************************************************** + | + | Dokka Developer Docs: $link + | + |*************************************************************************************************** + | + """.trimMargin() + ) + } } diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/architecture_overview.md b/docs-developer/docs/developer_guide/architecture/architecture_overview.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/architecture/architecture_overview.md rename to docs-developer/docs/developer_guide/architecture/architecture_overview.md diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md b/docs-developer/docs/developer_guide/architecture/data_model/documentable_model.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md rename to docs-developer/docs/developer_guide/architecture/data_model/documentable_model.md diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md b/docs-developer/docs/developer_guide/architecture/data_model/extra.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md rename to docs-developer/docs/developer_guide/architecture/data_model/extra.md diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md b/docs-developer/docs/developer_guide/architecture/data_model/page_content.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md rename to docs-developer/docs/developer_guide/architecture/data_model/page_content.md diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/base_plugin.md b/docs-developer/docs/developer_guide/architecture/extension_points/base_plugin.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/architecture/extension_points/base_plugin.md rename to docs-developer/docs/developer_guide/architecture/extension_points/base_plugin.md diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/core_extension_points.md b/docs-developer/docs/developer_guide/architecture/extension_points/core_extension_points.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/architecture/extension_points/core_extension_points.md rename to docs-developer/docs/developer_guide/architecture/extension_points/core_extension_points.md diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/extension_points.md b/docs-developer/docs/developer_guide/architecture/extension_points/extension_points.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/architecture/extension_points/extension_points.md rename to docs-developer/docs/developer_guide/architecture/extension_points/extension_points.md diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/extension_points/generation_implementations.md b/docs-developer/docs/developer_guide/architecture/extension_points/generation_implementations.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/architecture/extension_points/generation_implementations.md rename to docs-developer/docs/developer_guide/architecture/extension_points/generation_implementations.md diff --git a/docs-developer/src/doc/docs/developer_guide/community/slack.md b/docs-developer/docs/developer_guide/community/slack.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/community/slack.md rename to docs-developer/docs/developer_guide/community/slack.md diff --git a/docs-developer/src/doc/docs/developer_guide/introduction.md b/docs-developer/docs/developer_guide/introduction.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/introduction.md rename to docs-developer/docs/developer_guide/introduction.md diff --git a/docs-developer/src/doc/docs/developer_guide/plugin-development/introduction.md b/docs-developer/docs/developer_guide/plugin-development/introduction.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/plugin-development/introduction.md rename to docs-developer/docs/developer_guide/plugin-development/introduction.md diff --git a/docs-developer/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md b/docs-developer/docs/developer_guide/plugin-development/sample-plugin-tutorial.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/plugin-development/sample-plugin-tutorial.md rename to docs-developer/docs/developer_guide/plugin-development/sample-plugin-tutorial.md diff --git a/docs-developer/src/doc/docs/developer_guide/workflow.md b/docs-developer/docs/developer_guide/workflow.md similarity index 100% rename from docs-developer/src/doc/docs/developer_guide/workflow.md rename to docs-developer/docs/developer_guide/workflow.md diff --git a/docs-developer/src/doc/docs/dokka_colors.css b/docs-developer/docs/dokka_colors.css similarity index 100% rename from docs-developer/src/doc/docs/dokka_colors.css rename to docs-developer/docs/dokka_colors.css diff --git a/docs-developer/src/doc/docs/favicon.svg b/docs-developer/docs/favicon.svg similarity index 100% rename from docs-developer/src/doc/docs/favicon.svg rename to docs-developer/docs/favicon.svg diff --git a/docs-developer/src/doc/docs/index.md b/docs-developer/docs/index.md similarity index 100% rename from docs-developer/src/doc/docs/index.md rename to docs-developer/docs/index.md diff --git a/docs-developer/index.html b/docs-developer/index.html new file mode 100644 index 0000000000..1fb063422f --- /dev/null +++ b/docs-developer/index.html @@ -0,0 +1,8 @@ + + + + Dokka Developer Docs + + + + diff --git a/docs-developer/src/doc/mkdocs.yml b/docs-developer/mkdocs.yml similarity index 84% rename from docs-developer/src/doc/mkdocs.yml rename to docs-developer/mkdocs.yml index 533d32b153..9514b8ce4e 100644 --- a/docs-developer/src/doc/mkdocs.yml +++ b/docs-developer/mkdocs.yml @@ -1,5 +1,8 @@ site_name: Dokka +# note that site_dir is also specified in the Gradle task mkDocsBuild +site_dir: "build/mkdocs-current" + # Meta tags (placed in header) site_description: Dokka is an API documentation engine for Kotlin, performing the same function as the Javadoc tool for Java site_author: JetBrains @@ -26,6 +29,21 @@ theme: - navigation.instant - navigation.indexes - navigation.top + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: Switch to light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to system preference # Extensions markdown_extensions: diff --git a/docs-developer/requirements.txt b/docs-developer/requirements.txt new file mode 100644 index 0000000000..03c45041da --- /dev/null +++ b/docs-developer/requirements.txt @@ -0,0 +1,28 @@ +Babel==2.14.0 +certifi==2024.2.2 +charset-normalizer==3.3.2 +click==8.1.7 +colorama==0.4.6 +ghp-import==2.1.0 +idna==3.6 +Jinja2==3.1.3 +Markdown==3.5.2 +MarkupSafe==2.1.5 +mergedeep==1.3.4 +mkdocs==1.5.3 +mkdocs-material==9.5.10 +mkdocs-material-extensions==1.3.1 +packaging==23.2 +paginate==0.5.6 +pathspec==0.12.1 +platformdirs==4.2.0 +Pygments==2.17.2 +pymdown-extensions==10.7 +python-dateutil==2.8.2 +PyYAML==6.0.1 +pyyaml_env_tag==0.1 +regex==2023.12.25 +requests==2.31.0 +six==1.16.0 +urllib3==2.2.0 +watchdog==4.0.0