Add the link to homepage to the header if homepageLink is provided #3235

whyoleg · 2023-10-18T18:40:57Z

Added homepageLink parameter to DokkaBase plugin configuration. When setting it, icon with link to homepage will be shown near the theme switcher and search buttons in the header. Default icon is just platform-independent

vmishenev · 2023-10-19T16:49:10Z

plugins/base/src/main/kotlin/renderers/html/innerTemplating/DefaultTemplateModelFactory.kt

+        fun parseGithubInfo(link: String): Pair<String, String>? {
+            val (
+                _, // entire match
+                _, // optional 's' in http


What do you think about https?://github\\.com/([\\w,\\-_]+)/([\\w,\\-_]+)/.* where s is no capturing group?

yeah, agree, that should work, will fix it, thx!

IgnatBeresnev

For some reason, I don't see the icon in the header :( temporary preview link from GH actions

IgnatBeresnev · 2023-10-23T13:15:34Z

plugins/base/src/main/kotlin/renderers/html/innerTemplating/DefaultTemplateModelFactory.kt

+    private fun calculateSourceUrlFromSourceLinks(): String? {
+        val githubLinkRegex = Regex("http(s)?://github\\.com/([\\w,\\-_]+)/([\\w,\\-_]+)/.*")


Optional as it's not that important atm: it looks like this function will be called for each page, so it could be optimized slightly:

Afaik, each instance of Regex will compile the pattern under the hood, which takes some time, and it's generally advised to reuse it if it makes sense and is possible. I think in our case the Regex can be extracted into a companion or a top-level val or something, to be reused.

We only need to calculate the return value once for the whole DokkaConfiguration (it will not change in-between invocations), and then we can reuse it. But I can't think of where to save this result off the top of my head. Maybe as a lateinit or a lazy property somewhere? Any ideas? :)

If sourceUrl does not depend on a page, you can use buildSharedModel.

Thx!

extracted Regex to companion

moved calculation of link to buildSharedModel

plugins/base/src/test/kotlin/renderers/html/HeaderTest.kt

IgnatBeresnev · 2023-10-23T13:32:23Z

plugins/base/src/test/kotlin/renderers/html/HtmlRenderingOnlyTestBase.kt

-    override val context = MockContext(
+    override val context by lazy { context(configuration) }
+
+    fun context(testConfiguration: DokkaConfiguration): MockContext = MockContext(


(if you stick to HtmlRenderingOnlyTestBase and it's not reverted)

Was there some sort of a problem with it and this refactoring helped?

The problem is, while overall all of extensions are the same for all tests in file, configuration should be different per different tests - otherwise it's not possible to change some specific variables here.
F.e. in this case, I need to test output based on configuration.sourceSets[i].sourceLinks, and so configuration is different in each test function

whyoleg · 2023-10-24T08:50:18Z

For some reason, I don't see the icon in the header :(

Most likely this is because kotlinx.coroutines has no configuration of sourceLinks for root htmlMultiModule task.
Link to source: https://github.com/Kotlin/kotlinx.coroutines/blob/ed0cf7aa02b1266cb81e65e61b3a97b0e041a817/gradle/dokka.gradle.kts#L48
And also at least now it has sourceLinks configured for core project only (other modules don't have source in HTML generated, f.e. https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-android/kotlinx.coroutines.android/-handler-dispatcher/)

…efined

* no GitHub support by default * use URL from base plugin configuration * add integration test for the multi-module project that the homepage link exists everywhere

whyoleg · 2023-10-27T15:33:37Z

After internal discussion with @IgnatBeresnev some changes were applied:

replace GitHub image with some platform-independent icon (source of the link is in SVG: https://www.svgrepo.com/svg/416627/home-house-ui) - it's a temporary icon I believe
don't use sourceLinks to find homepage URL, because it not allows to fetch this configuration in reasonable way when building multi-module documentation - use base plugin configuration parameter

Question: Do we need to keep backward compatibility for DokkaBaseConfiguration?

IgnatBeresnev

👍👍

plugins/base/src/main/kotlin/DokkaBaseConfiguration.kt

IgnatBeresnev · 2023-10-30T13:47:12Z

it's a temporary icon I believe

Yep, we'll ask someone from the Kotlin Website team to help us with the icon and the styles, I've created a separate issue for that: #3300

vmishenev · 2023-11-01T17:23:21Z

...adle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/MultiModule0IntegrationTest.kt

@@ -73,6 +73,21 @@ class MultiModule0IntegrationTest : AbstractGradleIntegrationTest() {
            "Expected moduleC being mentioned in -modules.html"
        )

+        val indexHtmls = outputDir.walkTopDown().filter {
+            it.isFile && it.name == "index.html"


I think all html files except navigation might be checked.

vmishenev · 2023-11-01T17:27:20Z

plugins/base/src/main/resources/dokka/templates/includes/header.ftl

@@ -21,6 +21,9 @@
        <@source_set_selector.display/>
    </div>
    <div class="navigation-controls">
+        <#if homepageLink?has_content>
+            <div class="navigation-controls--btn navigation-controls--homepage" id="homepage-link" role="button"><a href="${homepageLink}"></a></div>


I have not checked but it seems to be <a href="${homepageLink}"> <div class="navigation-controls--btn navigation-controls--homepage" id="homepage-link" role="button"/></a>

Im not an html-expert, but at least my variant works. If to switch tags, it doesn't work at my side (may be need to adapt more code)
I think it could be rechecked in scope of #3300

whyoleg requested review from vmishenev and IgnatBeresnev October 18, 2023 18:40

whyoleg self-assigned this Oct 18, 2023

vmishenev approved these changes Oct 19, 2023

View reviewed changes

IgnatBeresnev reviewed Oct 23, 2023

View reviewed changes

whyoleg force-pushed the source-link branch from e38ff6b to 626a1cb Compare October 24, 2023 09:49

whyoleg added 5 commits October 27, 2023 13:39

Add the link to GitHub repo to the header if there are source links d…

c069217

…efined

calculate sourceUrl in shared model

52ed1f0

refactor tests to use BaseAbstractTest

a9c8eb3

revert changes in HtmlRenderingOnlyTestBase

506ef29

Rework homepage links:

6662802

* no GitHub support by default * use URL from base plugin configuration * add integration test for the multi-module project that the homepage link exists everywhere

whyoleg force-pushed the source-link branch from cbf05b2 to 6662802 Compare October 27, 2023 15:28

Update API dump

6fd4a09

whyoleg requested review from vmishenev and IgnatBeresnev October 27, 2023 15:33

IgnatBeresnev approved these changes Oct 30, 2023

View reviewed changes

plugins/base/src/main/kotlin/DokkaBaseConfiguration.kt Outdated Show resolved Hide resolved

IgnatBeresnev mentioned this pull request Oct 30, 2023

Verify CSS styles and the icon of the homepage link button #3300

Closed

Move new homepageLink parameter to the end

d5eab97

vmishenev approved these changes Nov 1, 2023

View reviewed changes

Check all html files except navigation in integration test

5505436

whyoleg merged commit 64cce58 into master Nov 7, 2023
11 checks passed

whyoleg deleted the source-link branch November 7, 2023 13:27

aSemy mentioned this pull request Nov 7, 2023

Dokka HTML: optionally add a custom link to source code homepage in navbar #2948

Closed

whyoleg changed the title ~~Add the link to GitHub repo to the header if there are source links defined~~ Add the link to homepage to the header if homepageLink is provided Nov 7, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add the link to homepage to the header if homepageLink is provided #3235

Add the link to homepage to the header if homepageLink is provided #3235

whyoleg commented Oct 18, 2023 •

edited

vmishenev Oct 19, 2023 •

edited

whyoleg Oct 24, 2023

IgnatBeresnev left a comment

IgnatBeresnev Oct 23, 2023

vmishenev Oct 23, 2023

whyoleg Oct 24, 2023

IgnatBeresnev Oct 23, 2023

whyoleg Oct 24, 2023

whyoleg commented Oct 24, 2023 •

edited

whyoleg commented Oct 27, 2023

IgnatBeresnev left a comment

IgnatBeresnev commented Oct 30, 2023 •

edited

vmishenev Nov 1, 2023

vmishenev Nov 1, 2023

whyoleg Nov 2, 2023

		private fun calculateSourceUrlFromSourceLinks(): String? {
		val githubLinkRegex = Regex("http(s)?://github\\.com/([\\w,\\-_]+)/([\\w,\\-_]+)/.*")

Add the link to homepage to the header if homepageLink is provided #3235

Add the link to homepage to the header if homepageLink is provided #3235

Conversation

whyoleg commented Oct 18, 2023 • edited

vmishenev Oct 19, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

IgnatBeresnev left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whyoleg commented Oct 24, 2023 • edited

whyoleg commented Oct 27, 2023

IgnatBeresnev left a comment

Choose a reason for hiding this comment

IgnatBeresnev commented Oct 30, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whyoleg commented Oct 18, 2023 •

edited

vmishenev Oct 19, 2023 •

edited

whyoleg commented Oct 24, 2023 •

edited

IgnatBeresnev commented Oct 30, 2023 •

edited