df-research

It's built using Writerside and published by a Github Action. 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 folder, and included in the StardustDocs/d.tree file.

Images all README files can be stored in docs/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.

Run the Build Docs Website configuration.
Run the Run Docs Website Locally configuration.
Open http://localhost:8000/home.html in your browser.
Shut down the server with Ctrl+C or close the terminal window.

Option 2: Manual Steps

Go to Writerside > DataFrame(d) > Export To > Build Docs Website or find Writerside web archive build in IDEA configuration.
Unzip the archive located at: ./build/ws/webHelpD2-all.zip
Start a local web server in the extracted folder (e.g., using Python or http-server utility):
```
python3 -m http.server
# or
http-server
```
Open http://localhost:8000/home.html in your browser.
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 by our "explainer" plugin callback proxy, which hooks into the TestBase class and retrieves the intermediate DataFrame expressions thanks to our "explainer" compiler plugin :plugins:expressions-converter.

We can also generate "normal" DataFrame samples for the website. This can be done using the OtherSamples class. Generated HTML files will be stored in docs/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.

Korro code samples

Code samples for the documentation website reside in core/.../test/.../samples/api (for samples that depend solely on dataframe-core), and tests/.../samples/api (for samples can depend on other I/O modules) and they are copied over to Markdown files in docs/StardustDocs/topics by Korro.