-
Notifications
You must be signed in to change notification settings - Fork 3
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
Extend Dokka support #352
Merged
Merged
Extend Dokka support #352
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
714c8a0
Add Dokka Gradle plugin dependency
tripolkaandrey f3836f9
Add `dokka-base` dependency
tripolkaandrey 38e90f9
Create script plugin to ease using Dokka in Java projects
tripolkaandrey 70e9fe2
Make naming consistent
tripolkaandrey f0be632
Add dependency for excluding code annotated with Internal annotation
tripolkaandrey dafe307
Add optional publish artifact with Dokka's output
tripolkaandrey 13cf71c
Make Dokka artifact publishing configuration consistent with other ar…
tripolkaandrey File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,85 @@ | ||
/* | ||
* Copyright 2022, TeamDev. All rights reserved. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* http://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Redistribution and use in source and/or binary forms, with or without | ||
* modification, must retain the above copyright notice and the following | ||
* disclaimer. | ||
* | ||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | ||
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | ||
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | ||
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | ||
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | ||
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | ||
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | ||
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | ||
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | ||
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
*/ | ||
|
||
import io.spine.internal.dependency.Dokka | ||
import java.time.LocalDate | ||
import org.jetbrains.dokka.base.DokkaBase | ||
import org.jetbrains.dokka.base.DokkaBaseConfiguration | ||
import org.jetbrains.dokka.gradle.DokkaTask | ||
|
||
plugins { | ||
id("org.jetbrains.dokka") | ||
} | ||
|
||
dependencies { | ||
/** | ||
* To generate the documentation as seen from Java perspective, the kotlin-as-java plugin was | ||
* added to the Dokka's classpath. | ||
* | ||
* @see <a href="https://github.com/Kotlin/dokka#output-formats"> | ||
* Dokka output formats</a> | ||
*/ | ||
dokkaPlugin(Dokka.KotlinAsJavaPlugin.lib) | ||
|
||
/** | ||
* To exclude pieces of code annotated with `@Internal` from the documentation a custom plugin | ||
* is added to the Dokka's classpath. | ||
* | ||
* @see <a href="https://github.com/SpineEventEngine/dokka-tools/tree/master/dokka-extensions"> | ||
* Custom Dokka Plugins</a> | ||
*/ | ||
dokkaPlugin(Dokka.SpineExtensions.lib) | ||
} | ||
|
||
tasks.withType<DokkaTask>().configureEach { | ||
dokkaSourceSets.configureEach { | ||
skipEmptyPackages.set(true) | ||
} | ||
|
||
outputDirectory.set(buildDir.resolve("docs/dokka")) | ||
|
||
val dokkaConfDir = rootDir.resolve("buildSrc/src/main/resources/dokka") | ||
|
||
/** | ||
* Dokka Base plugin allows to set a few properties to customize the output: | ||
* | ||
* - `customStyleSheets` property to which we can pass our css files overriding styles generated | ||
* by Dokka; | ||
* - `customAssets` property to provide resources. We need to provide an image with the name | ||
* "logo-icon.svg" to overwrite the default one used by Dokka; | ||
* - `separateInheritedMembers` when set to `true`, creates a separate tab in type-documentation | ||
* for inherited members. | ||
* | ||
* @see <a href="https://kotlin.github.io/dokka/1.6.10/user_guide/base-specific/frontend/#prerequisites"> | ||
* Dokka modifying frontend assets</a> | ||
*/ | ||
pluginConfiguration<DokkaBase, DokkaBaseConfiguration> { | ||
customStyleSheets = listOf(file("${dokkaConfDir.resolve("styles/custom-styles.css")}")) | ||
customAssets = listOf(file("${dokkaConfDir.resolve("assets/logo-icon.svg")}")) | ||
separateInheritedMembers = true | ||
footerMessage = "Copyright ${LocalDate.now().year}, TeamDev" | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
43 changes: 43 additions & 0 deletions
43
buildSrc/src/main/resources/dokka/styles/custom-styles.css
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,43 @@ | ||
/* | ||
* Copyright 2022, TeamDev. All rights reserved. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* http://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Redistribution and use in source and/or binary forms, with or without | ||
* modification, must retain the above copyright notice and the following | ||
* disclaimer. | ||
* | ||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | ||
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | ||
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | ||
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | ||
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | ||
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | ||
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | ||
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | ||
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | ||
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
*/ | ||
|
||
:root, | ||
:root.theme-dark { | ||
--color-dark: #007bff; | ||
} | ||
|
||
.library-name a::before { | ||
background-image: url('https://spine.io/img/spine-sign-white.svg') | ||
} | ||
|
||
.cover a, | ||
.main-subrow.keyValue a { | ||
font-family: monospace; | ||
} | ||
|
||
:root.theme-dark dt { | ||
color: #fff; | ||
} |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's make this expression syntactically similar to
protoJar
(see above).Also, the naming is important. We drop "include" prefix in order to make the whole thing shorter. Imagine if we don't:
Notice how much space this "include" takes? And the person who reads this needs to traverse down to the meaningful part, skipping "include" every time.