65 lines
3.5 KiB
Markdown
Vendored
65 lines
3.5 KiB
Markdown
Vendored
## The Documentation Website
|
|
|
|
This folder holds the source code of our documentation website:
|
|
[kotlin.github.io/dataframe](https://kotlin.github.io/dataframe).
|
|
|
|
It's built using [Writerside](https://www.jetbrains.com/writerside/) and published
|
|
by a [Github Action](../.github/workflows/main.yml).
|
|
The file structure largely mirrors the default Writerside structure.
|
|
For instance, if you want to add a new page to the website, this needs to be stored as an `.md` file in the
|
|
[StardustDocs/topics](./StardustDocs/topics) folder,
|
|
and included in the [StardustDocs/d.tree](./StardustDocs/d.tree) file.
|
|
|
|
Images all README files can be stored in [docs/imgs](./imgs).
|
|
|
|
## Running the Documentation Website Locally
|
|
|
|
⚠️ IFrames are not displayed when using the Writerside plugin preview. To view them correctly, you need to run the website locally.
|
|
|
|
### Option 1: Using IntelliJ IDEA Configurations
|
|
|
|
> Requires: `unzip` utility and **Python 3** installed in the environment. May not work properly on Windows.
|
|
|
|
1. Run the `Build Docs Website` configuration.
|
|
2. Run the `Run Docs Website Locally` configuration.
|
|
3. Open [http://localhost:8000/home.html](http://localhost:8000/home.html) in your browser.
|
|
4. Shut down the server with Ctrl+C or close the terminal window.
|
|
|
|
### Option 2: Manual Steps
|
|
|
|
1. Go to `Writerside > DataFrame(d) > Export To > Build Docs Website` or find Writerside web archive build in IDEA configuration.
|
|
2. Unzip the archive located at: `./build/ws/webHelpD2-all.zip`
|
|
3. Start a local web server in the extracted folder (e.g., using Python or `http-server` utility):
|
|
```bash
|
|
python3 -m http.server
|
|
# or
|
|
http-server
|
|
```
|
|
4. Open [http://localhost:8000/home.html](http://localhost:8000/home.html) in your browser.
|
|
5. Shut down the server with Ctrl+C or close the terminal window.
|
|
|
|
### 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/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/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/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)
|
|
(for samples that depend solely on `dataframe-core`),
|
|
and [tests/.../samples/api](../tests/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api) (for samples can depend on other I/O modules)
|
|
and they are copied over to Markdown files in [docs/StardustDocs/topics](./StardustDocs/topics)
|
|
by [Korro](https://github.com/devcrocod/korro).
|