Skip to content

Commit

Permalink
Doc style changes
Browse files Browse the repository at this point in the history
- Use scss to keep style sources clean
  - Add freefair scss gradle plugin
- Inject "including" section
- Make including section use tabs for code
- Make featurelist render properly for kt-fuzzy
- Apply dokka only to modules that need it (not common-test)
- Random misc. style changes

Signed-off-by: solonovamax <[email protected]>
  • Loading branch information
solonovamax committed Oct 2, 2023
1 parent 29747f6 commit a3e3a39
Show file tree
Hide file tree
Showing 12 changed files with 645 additions and 255 deletions.
2 changes: 2 additions & 0 deletions buildSrc/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,8 @@ dependencies {

implementation(gradlePlugin(libs.plugins.kotlinx.benchmark, libs.versions.kotlinx.benchmark))

implementation(gradlePlugin(libs.plugins.sass.base, libs.versions.freefair.sass))

// https://github.com/gradle/gradle/issues/15383
implementation(files(libs.javaClass.superclass.protectionDomain.codeSource.location))
}
Expand Down
71 changes: 63 additions & 8 deletions buildSrc/src/main/kotlin/kt-fuzzy.dokka.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -30,24 +30,37 @@ import ca.solostudios.dokkascript.plugin.DokkaScriptsConfiguration
import ca.solostudios.dokkascript.plugin.DokkaScriptsPlugin
import ca.solostudios.dokkastyles.plugin.DokkaStyleTweaksConfiguration
import ca.solostudios.dokkastyles.plugin.DokkaStyleTweaksPlugin
import io.freefair.gradle.plugins.sass.SassCompile
import java.time.Year
import org.apache.tools.ant.filters.ReplaceTokens
import org.intellij.lang.annotations.Language
import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.base.DokkaBase
import org.jetbrains.dokka.base.DokkaBaseConfiguration
import org.jetbrains.dokka.gradle.AbstractDokkaTask
import org.jetbrains.dokka.gradle.DokkaMultiModuleTask
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.gradle.DokkaTaskPartial
import sass.embedded_protocol.EmbeddedSass.OutputStyle

plugins {
id("org.jetbrains.dokka")
id("io.freefair.sass-base")
}

dependencies {
dokkaPlugin(libs.dokka.plugin.script)
dokkaPlugin(libs.dokka.plugin.style.tweaks)
}

sass {
omitSourceMapUrl = true
outputStyle = OutputStyle.COMPRESSED
sourceMapContents = false
sourceMapEmbed = false
sourceMapEnabled = false
}

tasks {
val rootDokkaDirectory = rootProject.projectDir.resolve("dokka")
val dokkaDirectories = if (project.rootProject != project)
Expand All @@ -56,7 +69,9 @@ tasks {
listOf(rootDokkaDirectory)

val processDokkaIncludes by register<ProcessResources>("processDokkaIncludes") {
from(dokkaDirectories.map { it.resolve("includes") })
from(dokkaDirectories.map { it.resolve("includes") }) {
exclude { it.name.startsWith("_") }
}

doFirst {
val projectInfo = ProjectInfo(
Expand All @@ -65,24 +80,64 @@ tasks {
version = project.version.toStringOrEmpty(),
)

filter { line ->
line.replace("", "<input type=\"checkbox\" readonly>")
.replace("", "<input type=\"checkbox\" readonly checked>")
.replace("\\[@ft-(\\w+)\\]".toRegex(), "<sup><a href=\"#footnote-\$1\">&#91;\$1&#93;</a></sup>")
.replace("\\[@ref-(\\d+)\\]".toRegex(), "<sup><a href=\"#reference-\$1\">&#91;\$1&#93;</a></sup>")
val including = rootDokkaDirectory.resolve("includes/_including.md").readText()

filter<ReplaceTokens>("tokens" to mapOf("including" to including), "beginToken" to "[%%", "endToken" to "%%]")

@Language("HTML")
val stringReplacements = listOf(
"" to """<input type="checkbox" readonly>""",
"" to """<input type="checkbox" readonly checked>""",
"- [x]" to """- <input class="checklist-item" type="checkbox" readonly>"""
)

@Language("RegExp")
val regexReplacements = listOf(
"\\[@ft-(\\w+)\\]".toRegex() to """<sup class="footnote"><a href="#footnote-$1">&#91;$1&#93;</a></sup>""",
"\\[@ref-(\\d+)\\]".toRegex() to """<sup class="reference"><a href="#reference-$1">&#91;$1&#93;</a></sup>""",
)

filter { sourceLine ->
stringReplacements.fold(sourceLine) { line, (old, new) ->
line.replace(old, new)
}.let { processedLine ->
regexReplacements.fold(processedLine) { line, (regex, replacement) ->
line.replace(regex, replacement)
}
}
}

expand("project" to projectInfo)
}

destinationDir = buildDir.resolve("dokka/includes")
destinationDir = buildDir.resolve("dokka").resolve("includes")
group = JavaBasePlugin.DOCUMENTATION_GROUP
}

val compileDokkaSass by register<SassCompile>("compileDokkaSass") {
group = BasePlugin.BUILD_GROUP
source = fileTree(rootDokkaDirectory.resolve("styles"))
destinationDir = buildDir.resolve("dokka/styles")
}

withType<AbstractDokkaTask>().configureEach {
inputs.files(rootDokkaDirectory)

dependsOn(compileDokkaSass)

pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
footerMessage = "© ${Year.now()} Copyright solo-studios"
separateInheritedMembers = false
customStyleSheets = rootDokkaDirectory.resolve("styles").listFiles()?.toList().orEmpty()

// Evil bullshit
val rootStyles = rootDokkaDirectory.resolve("styles").listFiles { file -> file.extension == "css" }?.toList().orEmpty()
val compiledStyles = rootDokkaDirectory.resolve("styles").listFiles { file ->
file.extension == "scss" && !file.name.startsWith("_")
}?.map {
buildDir.resolve("dokka/styles").resolve("${it.nameWithoutExtension}.css")
}.orEmpty()

customStyleSheets = rootStyles + compiledStyles
customAssets = rootDokkaDirectory.resolve("assets").listFiles()?.toList().orEmpty()
templatesDir = rootDokkaDirectory.resolve("templates")
}
Expand Down
22 changes: 11 additions & 11 deletions buildSrc/src/main/kotlin/kt-fuzzy.tasks.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,6 @@ import org.jetbrains.dokka.gradle.DokkaTask

plugins {
kotlin("multiplatform")

id("org.jetbrains.dokka")
}

val ext = the<ExtraPropertiesExtension>()
Expand All @@ -57,16 +55,18 @@ tasks {
dependsOn(withType<Jar>())
}

val dokkaHtml by named<DokkaTask>("dokkaHtml")
if (tasks.findByName("dokkaHtml") != null) {
val dokkaHtml by named<DokkaTask>("dokkaHtml")

val javadocJar by register<Jar>("javadocJar") {
dependsOn(dokkaHtml)
from(dokkaHtml.outputDirectory)
archiveClassifier = "javadoc"
group = JavaBasePlugin.DOCUMENTATION_GROUP
}
val javadocJar by register<Jar>("javadocJar") {
dependsOn(dokkaHtml)
from(dokkaHtml.outputDirectory)
archiveClassifier = "javadoc"
group = JavaBasePlugin.DOCUMENTATION_GROUP
}

artifacts {
archives(javadocJar)
artifacts {
archives(javadocJar)
}
}
}
55 changes: 55 additions & 0 deletions dokka/includes/_including.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
You can include ${project.module} in your project by adding the following:

<div class="tabbed-set tabbed-alternate" data-tabs="1:4">
<input id="__tabbed_1_1" name="__tabbed_1" type="radio"/>
<input id="__tabbed_1_2" name="__tabbed_1" type="radio"/>
<input checked="checked" id="__tabbed_1_3" name="__tabbed_1" type="radio"/>
<input id="__tabbed_1_4" name="__tabbed_1" type="radio"/>
<div class="tabbed-labels">
<label for="__tabbed_1_1">Maven</label>
<label for="__tabbed_1_2">Gradle Groovy</label>
<label for="__tabbed_1_3">Gradle Kotlin</label>
<label for="__tabbed_1_4">Gradle Version Catalog</label>
</div>
<div class="tabbed-content">
<div class="tabbed-block">

```xml
<dependencies>
<dependency>
<groupId>${project.group}</groupId>
<artifactId>${project.module}</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
```

</div>
<div class="tabbed-block">

```gradle
dependencies {
implementation '${project.group}:${project.module}:${project.version}'
}
```

</div>
<div class="tabbed-block">

```kotlin
dependencies {
implementation("${project.group}:${project.module}:${project.version}")
}
```

</div>
<div class="tabbed-block">

```toml
[libraries]
${project.module} = { group = "${project.group}", name = "${project.module}", version = "${project.version}" }
```

</div>
</div>
</div>
115 changes: 115 additions & 0 deletions dokka/scripts/tabbed.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
/*
* kt-fuzzy - A Kotlin library for fuzzy string matching
* Copyright (c) 2023 solonovamax <[email protected]>
*
* The file tabbed.js is part of kotlin-fuzzy
* Last modified on 30-09-2023 08:41 p.m.
*
* MIT License
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* KT-FUZZY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/


/**
* Link all tabs with same content
*/
function tabSync() {
const tabs = document.querySelectorAll(".tabbed-set > input")
for (const tab of tabs) {
tab.addEventListener("click", () => {
saveTabSelection(tab)

const current = document.querySelector(`label[for=${tab.id}]`)
const pos = current.getBoundingClientRect().top

syncTabsByName(current)

// Preserve scroll position
const delta = (current.getBoundingClientRect().top) - pos
window.scrollBy(0, delta)
})
}
}

/**
* Load previously selected tabs
*/
function loadSavedTabs() {
let allTabs = document.querySelectorAll(".tabbed-set > input");
let tabGroups = Array.from(allTabs).map((element) => {
return element.getAttribute("name")
})
tabGroups = unique(tabGroups);

for (const tabGroup of tabGroups) {
let tabId = loadTabIdsFromStorage(tabGroup);

if (tabId == null)
continue;

let tab = document.querySelector(`input[id="${tabId}"][name="${tabGroup}"]`)
tab.checked = true

const label = document.querySelector(`label[for=${tab.id}]`)
syncTabsByName(label)
}
}

/** @param {Element} localLabel */
function syncTabsByName(localLabel) {
const labelContent = localLabel.innerHTML
const labels = document.querySelectorAll('.tabbed-set > label, .tabbed-alternate > .tabbed-labels > label')
for (const label of labels) {
if (label.innerHTML === labelContent) {
let input = document.querySelector(`input[id=${label.getAttribute('for')}]`);
input.checked = true
if (label !== localLabel)
clearTabSelection(input)
}
}
}

/** @param {Element} tab */
function saveTabSelection(tab) {
const tabGroupId = tab.getAttribute("name")
const tabId = tab.id
localStorage.setItem(`${location.pathname}.${tabGroupId}`, tabId)
}

function clearTabSelection(tab) {
const tabGroupId = tab.getAttribute("name")
localStorage.removeItem(`${location.pathname}.${tabGroupId}`)
}

/** @param {String} tabGroupId */
function loadTabIdsFromStorage(tabGroupId) {
return localStorage.getItem(`${location.pathname}.${tabGroupId}`)
}

/** @param {any[]} array */
function unique(array) {
return Array.from(new Set(array));
}

window.addEventListener('DOMContentLoaded', () => {
// Load shit
loadSavedTabs()
tabSync()
})
47 changes: 47 additions & 0 deletions dokka/styles/_mixins.scss
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
/*!
* kt-fuzzy - A Kotlin library for fuzzy string matching
* Copyright (c) 2023 solonovamax <[email protected]>
*
* The file _mixins.scss is part of kotlin-fuzzy
* Last modified on 02-10-2023 01:08 p.m.
*
* MIT License
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* KT-FUZZY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/

$default-prefixes: (
'webkit',
'moz',
'ms',
);

/// Mixin to prefix a property
/// @author Kitty Giraudel
/// @param {String} $property - Property name
/// @param {*} $value - Property value
/// @param {List} $prefixes (()) - List of prefixes to print
@mixin vendor-prefix($property, $value, $prefixes: $default-prefixes) {
@each $prefix in $prefixes {
#{'-' + $prefix + '-' + $property}: $value;
}

// Output standard non-prefixed declaration
#{$property}: $value;
}
Loading

0 comments on commit a3e3a39

Please sign in to comment.