Merge branch 'newVersionDec2024'

.github/workflows/build-documentation.yml

@@ -0,0 +1,58 @@
+name: Build documentation
+
+on:
+  push:
+  workflow_dispatch:
+
+env:
+  INSTANCE: 'Writerside/strumenta'
+  DOCKER_VERSION: '243.21565'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      algolia_artifact: ${{ steps.define-ids.outputs.algolia_artifact }}
+      artifact: ${{ steps.define-ids.outputs.artifact }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Define instance id and artifacts
+        id: define-ids
+        run: |
+          INSTANCE=${INSTANCE#*/}
+          INSTANCE_ID_UPPER=$(echo "$INSTANCE" | tr '[:lower:]' '[:upper:]')
+          ARTIFACT="starlasu-documentation-${INSTANCE_ID_UPPER}.zip"
+          ALGOLIA_ARTIFACT="algolia-indexes-${INSTANCE_ID_UPPER}.zip"
+
+          # Print the values
+          echo "INSTANCE_ID_UPPER: $INSTANCE_ID_UPPER"
+          echo "ARTIFACT: $ARTIFACT"
+          echo "ALGOLIA_ARTIFACT: $ALGOLIA_ARTIFACT"
+
+          # Set the environment variables and outputs
+          echo "INSTANCE_ID_UPPER=$INSTANCE_ID_UPPER" >> $GITHUB_ENV
+          echo "ARTIFACT=$ARTIFACT" >> $GITHUB_ENV
+          echo "ALGOLIA_ARTIFACT=$ALGOLIA_ARTIFACT" >> $GITHUB_ENV
+          echo "artifact=$ARTIFACT" >> $GITHUB_OUTPUT
+          echo "algolia_artifact=$ALGOLIA_ARTIFACT" >> $GITHUB_OUTPUT
+
+      - name: Build docs using Writerside Docker builder
+        uses: JetBrains/writerside-github-action@v4
+        with:
+          instance: ${{ env.INSTANCE }}
+          artifact: ${{ env.ARTIFACT }}
+          docker-version: ${{ env.DOCKER_VERSION }}
+
+      - name: Save artifact with build results
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: |
+            artifacts/${{ env.ARTIFACT }}
+            artifacts/report.json
+            artifacts/${{ env.ALGOLIA_ARTIFACT }}
+          retention-days: 7

README.md

@@ -1,24 +1,9 @@
-# StarLasu
-StarLasu is the missing link between source code and a convenient structure for its interpretation and manipulation: an AST.
-When building an interpreter, transpiler, compiler, editor, static analysis tool, etc., at Strumenta we always implement the following pipeline:
-
-Source code --ANTLR4 parser--> Parse tree __--StarLasu--> AST__ --Further processing--> ... --> Result
-
-StarLasu is both the above methodology and a collection of runtime libraries to support it in Java, Kotlin, Python, Javascript, Typescript, and C#:
-
-* [Kolasu](https://github.com/Strumenta/kolasu): it was the first library to be developed. It supports development in Kotlin and Java.
-* [Tylasu](https://github.com/Strumenta/tylasu): it supports development in Typescript and Javascript. We're working to advance it to be on par with Kolasu.
-* [Pylasu](https://github.com/Strumenta/pylasu): it supports development in Python. It is fairly recent but it is progressing quite rapidly.
-* [Sharplasu](https://github.com/Strumenta/sharplasu): it supports development in C#. It is the most recently created and it is ongoing active development.
-
-## Documentation
-
-Documentation for StarLasu is available [here](https://github.com/Strumenta/StarLasu/tree/main/documentation).
+# Starlasu
+This project contains the documentation on the Starlasu approach, which is 
+published [here](https://github.com/Strumenta/StarLasu/tree/main/documentation).
 
 ## Publication
 
-You will need pandoc with pdflatex (`brew install pandoc basictex`).
+We generate the documentation to be published using JetBrains's Writerside.
 
 Updating the published version requires manually uploading the generated files to Netlify. At the moment Federico is the only one who has access.
-
-You will need to run generatedoc.sh, then take the content of htmldoc and renamed the html file to index.html, zip the html file with the css directory and upload it to netlify.

Writerside/c.list

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE categories
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
+<categories>
+    <category id="wrs" name="Writerside documentation" order="1"/>
+</categories>

Writerside/cfg/buildprofiles.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE buildprofiles SYSTEM "https://resources.jetbrains.com/writerside/1.0/build-profiles.dtd">
+<buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
+    <variables></variables>
+    <build-profile instance="strumenta">
+        <variables>
+            <noindex-content>false</noindex-content>
+        </variables>
+    </build-profile>
+
+</buildprofiles>

Writerside/strumenta.tree

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE instance-profile
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
+
+<instance-profile id="strumenta"
+                 name="The Starlasu Approach"
+                 start-page="StarlasuOverview.md">
+
+    <toc-element topic="StarlasuOverview.md"/>
+    <toc-element topic="DualCodeModelAPIs.md"/>
+    <toc-element topic="ChiselMethod.md"/>
+    <toc-element topic="Validation.md"/>
+    <toc-element topic="ASTRepresentation.md"/>
+    <toc-element topic="ASTTraversalAndQuerying.md"/>
+    <toc-element topic="CodeGeneration.md"/>
+    <toc-element topic="DocumentationGeneration.md"/>
+    <toc-element topic="EditorSupport.md"/>
+    <toc-element topic="Interoperability.md">
+        <toc-element topic="EMFInteroperability.md"/>
+    </toc-element>
+    <toc-element topic="SemanticEnrichment.md"/>
+    <toc-element topic="Testing.md"/>
+    <toc-element topic="TransformationFramework.md"/>
+    <toc-element topic="Use-Cases.md">
+        <toc-element topic="building-transpiler.md"/>
+        <toc-element topic="building-parser.md"/>
+        <toc-element topic="building-codegenerator.md"/>
+    </toc-element>
+    <toc-element topic="CommonElements.md"/>
+    <toc-element topic="CrossPlatformParsers.md"/>
+    <toc-element topic="Naming.md"/>
+    <toc-element topic="OriginAndDestination.md"/>
+    <toc-element topic="ParseTreeToASTMapping.md"/>
+    <toc-element topic="Position.md"/>
+    <toc-element topic="Serialization.md"/>
+</instance-profile>