Website docs landing

.github/README_GH_ACTIONS.md

@@ -22,7 +22,7 @@ Anytime the source code changes on [master](https://github.com/Kotlin/dataframe/
 this [GitHub Action](./workflows/generated-sources-master.yml) makes sure
 [`processKDocsMain`](../KDOC_PREPROCESSING.md),
 and `korro` are run. If there have been any changes in either [core/generated-sources](../core/generated-sources) or
-[docs/StardustDocs/snippets](../docs/StardustDocs/snippets), these are auto-committed to the branch, to keep
+[docs/StardustDocs/resources/snippets](../docs/StardustDocs/resources/snippets), these are auto-committed to the branch, to keep
 it up to date.
 
 ### Show generated code in PR

.github/workflows/generated-sources-master.yml

@@ -26,7 +26,7 @@ jobs:
         run: |
           git config --global user.name 'github-actions[bot]'
           git config --global user.email 'github-actions[bot]@users.noreply.github.com'
-          git add './core/generated-sources' './dataframe-csv/generated-sources' './docs/StardustDocs/snippets' './docs/StardustDocs/topics'
+          git add './core/generated-sources' './dataframe-csv/generated-sources' './docs/StardustDocs/resources/snippets' './docs/StardustDocs/topics'
           git diff --staged --quiet || git commit -m "Automated commit of generated code"
           git push
         env:

.github/workflows/generated-sources.yml

@@ -42,14 +42,14 @@ jobs:
 
       - name: Check for changes in generated sources
         id: git-diff
-        run: echo "changed=$(if git diff --quiet './core/generated-sources' './dataframe-csv/generated-sources' './docs/StardustDocs/snippets' './docs/StardustDocs/topics'; then echo 'false'; else echo 'true'; fi)" >> $GITHUB_OUTPUT
+        run: echo "changed=$(if git diff --quiet './core/generated-sources' './dataframe-csv/generated-sources' './docs/StardustDocs/resources/snippets' './docs/StardustDocs/topics'; then echo 'false'; else echo 'true'; fi)" >> $GITHUB_OUTPUT
 
       - name: Commit and push if changes
         id: git-commit
         if: steps.git-diff.outputs.changed == 'true'
         run: |
           git checkout -b generated-sources/docs-update-${{ github.run_number }}
-          git add './core/generated-sources' './dataframe-csv/generated-sources' './docs/StardustDocs/snippets' './docs/StardustDocs/topics'
+          git add './core/generated-sources' './dataframe-csv/generated-sources' './docs/StardustDocs/resources/snippets' './docs/StardustDocs/topics'
           git commit -m "Update generated sources with recent changes"
           git push origin generated-sources/docs-update-${{ github.run_number }}
           echo "commit=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT

KDOC_PREPROCESSING.md

@@ -693,7 +693,7 @@ A fully interactive, single-source-of-truth grammar for the Columns Selection DS
 There's a special annotation, `@ExportAsHtml`, that allows you to export the content of the KDoc of the annotated
 function, interface, or class as HTML.
 The Markdown of the KDoc is rendered to HTML using [JetBrains/markdown](https://github.com/JetBrains/markdown) and, in
-the case of DataFrame, put in [./docs/StardustDocs/snippets/kdocs](./docs/StardustDocs/snippets/kdocs).
+the case of DataFrame, put in [./docs/StardustDocs/resources/snippets/kdocs](docs/StardustDocs/resources/snippets/kdocs).
 From there, the HTML can be included in any WriterSide page as an iFrame.
 This can be done using our custom `<dataFrame src=""/>` tag.
 

build.gradle.kts

@@ -154,6 +154,7 @@ val modulesUsingJava11 = with(projects) {
         dataframeJupyter,
         dataframeGeo,
         examples.ideaExamples.titanic,
+        tests,
     )
 }.map { it.path }
 

core/README.md

@@ -25,15 +25,15 @@ by [Korro](https://github.com/devcrocod/korro).
 
 Aside from code samples, `@TransformDataFrameExpressions` annotated test functions also generate sample
 dataframe HTML files that can be used as iFrames on the documentation website.
-They are tested, generated, and copied over to [docs/StardustDocs/snippets](../docs/StardustDocs/snippets) by
+They are tested, generated, and copied over to [docs/StardustDocs/resources/snippets](../docs/StardustDocs/resources/snippets) by
 our "explainer" [plugin callback proxy](./src/test/kotlin/org/jetbrains/kotlinx/dataframe/explainer),
 which hooks into [the TestBase class](./src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/TestBase.kt) and
 retrieves the intermediate DataFrame expressions thanks to our "explainer" compiler plugin
 [:plugins:expressions-converter](../plugins/expressions-converter).
 
 We can also generate "normal" DataFrame samples for the website. This can be done using the
 [OtherSamples class](./src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt). Generated
-HTML files will be stored in [docs/StardustDocs/snippets/manual](../docs/StardustDocs/snippets/manual).
+HTML files will be stored in [docs/StardustDocs/resources/snippets/manual](../docs/StardustDocs/resources/snippets/manual).
 
 ### KoDEx
 
@@ -45,4 +45,4 @@ See the [KDoc Preprocessing Guide](../KDOC_PREPROCESSING.md) for more informatio
 
 KDocs can also be exported to HTML, for them to be reused on the website.
 Elements annotated with `@ExportAsHtml` will have their generated content be copied over to
-[docs/StardustDocs/snippets/kdocs](../docs/StardustDocs/snippets/kdocs).
+[docs/StardustDocs/resources/snippets/kdocs](../docs/StardustDocs/resources/snippets/kdocs).

core/build.gradle.kts

@@ -145,7 +145,7 @@ val clearSamplesOutputs by tasks.creating {
 
     doFirst {
         delete {
-            val generatedSnippets = fileTree(file("../docs/StardustDocs/snippets"))
+            val generatedSnippets = fileTree(file("../docs/StardustDocs/resources/snippets"))
                 .exclude("**/manual/**", "**/kdocs/**")
             delete(generatedSnippets)
         }
@@ -155,7 +155,7 @@ val clearSamplesOutputs by tasks.creating {
 val addSamplesToGit by tasks.creating(GitTask::class) {
     directory = file(".")
     command = "add"
-    args = listOf("-A", "../docs/StardustDocs/snippets")
+    args = listOf("-A", "../docs/StardustDocs/resources/snippets")
 }
 
 val copySamplesOutputs = tasks.register<JavaExec>("copySamplesOutputs") {
@@ -218,7 +218,7 @@ val processKDocsMain by creatingRunKodexTask(processKDocsMainSources) {
     outputReadOnly = false
 
     exportAsHtml {
-        dir = file("../docs/StardustDocs/snippets/kdocs")
+        dir = file("../docs/StardustDocs/resources/snippets/kdocs")
     }
     finalizedBy("runKtlintFormatOverGeneratedSourcesSourceSet")
 }

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/explainer/PluginCallbackProxy.kt

@@ -131,7 +131,7 @@ object PluginCallbackProxy : PluginCallback {
         File(korro, group).writeText(
             """
             
-            <dataFrame src="$group.html"/>
+            <inline-frame src="resources/$group.html" width="100%"/>
             """.trimIndent(),
         )
     }

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/explainer/SampleAggregator.kt

@@ -13,7 +13,7 @@ fun main() {
         .groupBy {
             it.nameWithoutExtension.substringBefore("_")
         }.mapValues { (name, files) ->
-            val target = File("../docs/StardustDocs/snippets")
+            val target = File("../docs/StardustDocs/resources/snippets")
             val original = files
                 .firstOrNull { it.nameWithoutExtension.contains("properties") }
                 ?: files.first()

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt

@@ -21,7 +21,7 @@ class OtherSamples {
     }
 
     private fun writeTable(df: AnyFrame, name: String) {
-        val dir = File("../docs/StardustDocs/snippets/manual").also { it.mkdirs() }
+        val dir = File("../docs/StardustDocs/resources/snippets/manual").also { it.mkdirs() }
         val html = df.toStandaloneHtml(getFooter = WritersideFooter) + WritersideStyle
         html.writeHtml(File(dir, "$name.html"))
     }

dataframe-csv/build.gradle.kts

@@ -91,7 +91,7 @@ val processKDocsMain by creatingRunKodexTask(processKDocsMainSources) {
     outputReadOnly = false
 
     exportAsHtml {
-        dir = file("../docs/StardustDocs/snippets/kdocs")
+        dir = file("../docs/StardustDocs/resources/snippets/kdocs")
     }
     finalizedBy("runKtlintFormatOverGeneratedSourcesSourceSet")
 }

docs/README.md

@@ -15,20 +15,20 @@ Images all README files can be stored in [docs/imgs](./imgs).
 ### Explainer dataframes
 `@TransformDataFrameExpressions` annotated test functions generate sample
 dataframe HTML files that can be used as iFrames on the documentation website.
-They are tested, generated, and copied over to [docs/StardustDocs/snippets](./StardustDocs/snippets) by
+They are tested, generated, and copied over to [docs/StardustDocs/resources/snippets](StardustDocs/resources/snippets) by
 our "explainer" [plugin callback proxy](../core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/explainer),
 which hooks into [the TestBase class](../core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/TestBase.kt) and
 retrieves the intermediate DataFrame expressions thanks to
 our "explainer" compiler plugin [:plugins:expressions-converter](../plugins/expressions-converter).
 
 We can also generate "normal" DataFrame samples for the website. This can be done using the
 [OtherSamples class](../core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/OtherSamples.kt). Generated
-HTML files will be stored in [docs/StardustDocs/snippets/manual](./StardustDocs/snippets/manual).
+HTML files will be stored in [docs/StardustDocs/resources/snippets/manual](StardustDocs/resources/snippets/manual).
 
 ### KDoc Preprocessor
 KDocs can also be exported to HTML, for them to be reused on the website.
 Elements annotated with `@ExportAsHtml` will have their generated content be copied over to
-[docs/StardustDocs/snippets/kdocs](./StardustDocs/snippets/kdocs).
+[docs/StardustDocs/resources/snippets/kdocs](StardustDocs/resources/snippets/kdocs).
 
 ### Korro code samples
 Code samples for the documentation website reside in [core/.../test/.../samples/api](../core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api)

docs/StardustDocs/cfg/buildprofiles.xml

@@ -16,6 +16,7 @@
         <analytics-head-script-file>resize-iframes.js</analytics-head-script-file>
         <enable-browser-edits>true</enable-browser-edits>
         <browser-edits-url>https://github.com/Kotlin/dataframe/edit/master/docs/StardustDocs/</browser-edits-url>
+        <include-in-head>include-head.html</include-in-head>
     </variables>
     <sitemap change-frequency="monthly"/>
     <build-profile instance="d">

docs/StardustDocs/cfg/include-head.html

@@ -0,0 +1 @@
+<script src="static/custom.js"></script>

docs/StardustDocs/cfg/static/custom.js

@@ -0,0 +1,67 @@
+window.addEventListener('load', () => {
+    function updateIframeThemes(theme) {
+        const iframes = document.querySelectorAll('iframe');
+
+        iframes.forEach((iframe) => {
+            if (iframe.contentWindow && iframe.contentWindow.document) {
+                iframe.contentWindow.document.documentElement.setAttribute('theme', theme);
+            }
+        });
+    }
+
+    function observeHtmlClassChanges() {
+        const htmlElement = document.documentElement;
+
+        const observer = new MutationObserver((mutations) => {
+            mutations.forEach((mutation) => {
+                if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
+                    const theme = htmlElement.classList.contains('theme-light') ? 'light' : 'dark';
+                    updateIframeThemes(theme);
+                }
+            });
+        });
+
+        observer.observe(htmlElement, { attributes: true });
+    }
+
+    window.addEventListener('message', (event) => {
+        if (event.data.type === 'iframeHeight') {
+            document.querySelectorAll('iframe').forEach((iframe) => {
+                if (iframe.contentWindow === event.source) {
+                    iframe.style.height = event.data.height + 'px';
+                }
+            });
+        }
+    });
+
+    function observeIframe(iframe) {
+        const theme = document.documentElement.classList.contains('theme-light') ? 'light' : 'dark';
+
+        function sendTheme() {
+            iframe.contentDocument.documentElement.setAttribute('theme', theme);
+        }
+
+        iframe.addEventListener('load', sendTheme);
+        if (iframe.contentDocument.readyState === 'complete') sendTheme();
+    }
+
+    document.querySelectorAll('iframe').forEach(observeIframe);
+
+    const bodyObserver = new MutationObserver((mutations) => {
+        mutations.forEach((mutation) => {
+            mutation.addedNodes.forEach((node) => {
+                if (node.tagName === 'IFRAME') observeIframe(node);
+                else if (node.querySelectorAll) {
+                    node.querySelectorAll('iframe').forEach(observeIframe);
+                }
+            });
+        });
+    });
+
+    bodyObserver.observe(document.body, { childList: true, subtree: true });
+
+    observeHtmlClassChanges();
+
+    const initialTheme = document.documentElement.classList.contains('theme-light') ? 'light' : 'dark';
+    updateIframeThemes(initialTheme);
+});

docs/StardustDocs/d.tree

@@ -5,8 +5,14 @@
 <instance-profile id="d"
                  name="Dataframe"
                  status="release"
-                 start-page="overview.md">
+                 start-page="Home.topic">
+    <toc-element topic="Home.topic"/>
+    <toc-element topic="Guides-And-Examples.md">
+        <toc-element topic="quickstart.md"/>
+    </toc-element>
+
     <toc-element topic="gettingStarted.md" accepts-web-file-names="installation.html">
+        <toc-element topic="gettingStartedKotlinNotebook.md"/>
         <toc-element topic="gettingStartedGradle.md"/>
         <toc-element topic="gettingStartedJupyterNotebook.md"/>
         <toc-element topic="gettingStartedDatalore.md"/>
@@ -191,4 +197,7 @@
         <toc-element topic="Trobleshooting.md"/>
     </toc-element>
     <toc-element href="https://github.com/Kotlin/dataframe/tree/master/examples" toc-title="Examples"/>
+    <toc-element topic="Compiler-Plugin.md"/>
+    <toc-element topic="_shadow_resources.md" hidden="true"/>
+    <toc-element topic="_shadow_resources_snippets.md" hidden="true"/>
 </instance-profile>