jolie · fmontesi · Nov 21, 2024 · Oct 21, 2024 · Oct 23, 2024 · Nov 15, 2024
diff --git a/.github/workflows/stdlibs-docs.yml b/.github/workflows/stdlibs-docs.yml
@@ -0,0 +1,127 @@
+name: "Build and Push Standard Library Documentation"
+
+on:
+  workflow_dispatch:
+  workflow_run:
+    workflows:
+      - Java CI
+    types:
+      - completed
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      jolie_version: ${{ steps.jolie_version.outputs.jolie_version }}
+      summary_string: ${{ steps.generate.outputs.summary_string }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up JDK
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin' # See 'Supported distributions' for available options
+          java-version: 21
+          cache: 'maven'
+      - name: Build with Maven
+        run: mvn install --file pom.xml
+      - name: "Set up JOLIE_HOME environment"
+        shell: bash
+        run: |
+          echo "JOLIE_HOME=${{ github.workspace }}/dist/jolie" >> "$GITHUB_ENV"
+      - name: Set up PATH environment
+        shell: bash
+        run: |
+          echo "${{ github.workspace }}/dist/launchers/unix" >> $GITHUB_PATH
+      - name: Generate Documentation
+        id: generate
+        shell: bash
+        run:  |
+          mkdir -p docs
+          SUMMARY=""
+          find ${{ github.workspace }}/packages -maxdepth 1 -type f -not -regex ".*_.*" -print | sort | ( while read -r file; do
+              MODULE_NAME="$(basename -- "$file")"
+              SERVICE_NAME="$(a=($(cat $file | grep -o -E '^service.*{$'));echo ${a[1]})"
+
+              SUMMARY="$SUMMARY    - [${MODULE_NAME%.ol}](language-tools-and-standard-library/standard-library-api/${MODULE_NAME%.ol}.md)\n"
+              # run joliedoc
+              joliedoc "$file" --internals --out-type md
+              # insert module name and move necessary file to docs
+              IPLOCALFILES="$(grep -rnwl 'joliedoc/' --exclude="index.md" --exclude="Overview.md" -e "local")"
+              # select input port document file
+              if echo $IPLOCALFILES | tr ' ' '\n'| grep -qiF "$SERVICE_NAME"; then
+                  # try find the file by service name
+                  IPLOCALFILE="$(echo $IPLOCALFILES | tr ' ' '\n' | grep -iF $SERVICE_NAME)"
+              else
+                  # select first file
+                  IPLOCALFILE="$(echo $IPLOCALFILES | tr ' ' '\n' | head -1)"
+              fi
+              # insert service name
+              sed -i "s/# Service/# Service $SERVICE_NAME\n\n> from ${MODULE_NAME%.ol} import $SERVICE_NAME/" "$IPLOCALFILE"
+              # move file to docs
+              mv "$IPLOCALFILE" "${{ github.workspace }}/docs/${MODULE_NAME%.ol}.md"
+              echo "generated doc for '$file', found '$SERVICE_NAME', moved generated doc file '$IPLOCALFILE' to 'docs/$MODULE_NAME'";
+
+              # remove joliedoc
+              rm -rf ${{ github.workspace }}/joliedoc
+          done
+
+          echo "summary_string<<EOF" >> $GITHUB_OUTPUT 
+          echo "$SUMMARY" >> $GITHUB_OUTPUT 
+          echo "EOF" >> $GITHUB_OUTPUT )
+      - name: Cache Docs
+        id: cache-docs
+        uses: actions/cache/save@v4
+        with:
+          path: docs
+          key: docs-${{ github.sha }}
+      - name: Retrive Jolie version
+        id: jolie_version
+        run:
+          echo "jolie_version=$(cat pom.xml | grep -o -P '(?<=<jolie.version>).*(?=</jolie.version>)')" >> $GITHUB_OUTPUT
+  push:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache/restore@v4
+        id: cache
+        with:
+          path: docs
+          key: docs-${{ github.sha }}
+      - name: echo jolie version
+        run: echo ${{ needs.build.outputs.jolie_version }}
+      - name: get jolie docs branch
+        id: jolie_branch
+        run: echo "jolie_branch=v$(echo ${{ needs.build.outputs.jolie_version }} | sed -E 's/(.*)([[:digit:]]+)/\1x/')" >> $GITHUB_OUTPUT
+      - name: Push to docs repository
+        env:
+          API_TOKEN_GITHUB: ${{ secrets.JOLIE_DOCS_WRITE_CONTENTS }}
+          BRANCH: ${{ steps.jolie_branch.outputs.jolie_branch }}
+          DOC_PATH: src/language-tools-and-standard-library/standard-library-api
+        run: |
+          CLONE_DIR=$(mktemp -d)
+          DEST_COPY=$CLONE_DIR/$DOC_PATH
+          echo "Clone docs repository"
+          git config --global user.email "[email protected]"
+          git config --global user.name "GitAction"
+          git clone --single-branch --branch "$BRANCH" "https://x-access-token:[email protected]/jolie/docs.git" "$CLONE_DIR"
+          echo "Copy generated doc to docs repository"
+          mkdir -p "$DEST_COPY"
+          cp -R "docs" "$DEST_COPY"
+          cd "$CLONE_DIR"
+
+          # replace SUMMARY.md
+          SUMMARY="${{ needs.build.outputs.summary_string }}"
+
+          sed -z -i "s|/standard-library-api/README.md).*# Errors|/standard-library-api/README.md)\n$SUMMARY\n\n# Errors|" src/SUMMARY.md
+
+          echo "Add git commit"
+          git add .
+          if git status | grep -q "Changes to be committed"
+          then
+            git commit --message "Update stdlib docs from Jolie commit/${GITHUB_SHA}"
+            echo "Pushing git commit"
+            git push -u origin HEAD:"$BRANCH"
+          else
+            echo "No changes detected"
+          fi
diff --git a/include/metajolie.iol b/include/metajolie.iol
@@ -41,7 +41,7 @@ type GetMetaDataRequest: void {
 }
 
 type GetMetaDataResponse: void {
-  .service: Service             //< the definition of the service
+  .service*: Service             //< the definition of the service
   .input*: Port                 //< the definitions of all the input ports
   .output*: Port                //< the definitions of all the output ports
   .interfaces*: Interface       //< the definitions of all the interfaces

diff --git a/include/services/metajolie/public/interfaces/metajolie_javaservice.iol b/include/services/metajolie/public/interfaces/metajolie_javaservice.iol
@@ -41,7 +41,7 @@ type GetMetaDataRequest: void {
 }
 
 type GetMetaDataResponse: void {
-  .service: Service             //< the definition of the service
+  .service*: Service             //< the definition of the service
   .input*: Port                 //< the definitions of all the input ports
   .output*: Port                //< the definitions of all the output ports
   .interfaces*: Interface       //< the definitions of all the interfaces

diff --git a/packages/metajolie.ol b/packages/metajolie.ol
@@ -57,7 +57,7 @@ type GetMetaDataRequest: void {
 }
 
 type GetMetaDataResponse: void {
-  .service: Service             //< the definition of the service
+  .service*: Service             //< the definition of the service
   .input*: Port                 //< the definitions of all the input ports
   .output*: Port                //< the definitions of all the output ports
   .interfaces*: Interface       //< the definitions of all the interfaces

diff --git a/pom.xml b/pom.xml
@@ -298,15 +298,7 @@
 									<directory>${basedir}/tools/joliedoc</directory>
 									<includes>
 										<include>joliedoc.ol</include>
-										<include>cardinality-template.html</include>
-										<include>native-type-template.html</include>
-										<include>overview-page-template.html</include>
-										<include>port-page-template.html</include>
-										<include>sub-type-template.html</include>
-										<include>type-template.html</include>
-										<include>typeinline-template.html</include>
-										<include>typelink-template.html</include>
-										<include>index-template.html</include>
+										<include>templates/**</include>
 									</includes>
 									<filtering>true</filtering>
 								</resource>

diff --git a/tools/joliedoc/joliedoc.ol b/tools/joliedoc/joliedoc.ol
@@ -366,9 +366,9 @@ service JolieDoc {
 
                     max_files = #files 
                     if ( __port_type == "input" ) {
-                        endname = "IPort.html"
+                        endname = "IPort." + type
                     } else {
-                        endname = "OPort.html"
+                        endname = "OPort." + type
                     }
                     files[ max_files ].filename = ptt.name + endname
                     files[ max_files ].html = portPage
@@ -381,42 +381,47 @@ service JolieDoc {
         install( Abort => nullProcess )
     }
 
-    init {
-        getServiceDirectory@File()( joliedoc_directory )
-        // loading templates
-        readFile@File( { filename = joliedoc_directory + "/overview-page-template.html" } )( ovh_template )
-        readFile@File( { filename = joliedoc_directory + "/port-page-template.html" } )( port_page_template )
-        readFile@File( { filename = joliedoc_directory + "/index-template.html" } )( index_template )
-        // loading partials
-        partials[0].name = "cardinality-template"
-        readFile@File( { filename = joliedoc_directory + "/cardinality-template.html" } )( partials[0].template )
-        partials[1].name = "native-type-template"
-        readFile@File( { filename = joliedoc_directory + "/native-type-template.html" } )( partials[1].template )
-        partials[2].name = "sub-type-template"
-        readFile@File( { filename = joliedoc_directory + "/sub-type-template.html" } )( partials[2].template )
-        partials[3].name = "type-template"
-        readFile@File( { filename = joliedoc_directory + "/type-template.html" } )( partials[3].template )
-        partials[4].name = "typeinline-template"
-        readFile@File( { filename = joliedoc_directory + "/typeinline-template.html" } )( partials[4].template )
-        partials[5].name = "typelink-template"
-        readFile@File( { filename = joliedoc_directory + "/typelink-template.html" } )( partials[5].template )
-
-    }
-
     main {
 
-        if ( #args == 0 || #args > 2 ) {
-            println@Console( "Usage: joliedoc <filename> [--internals ]")()
+        if ( #args == 0 ) {
+            println@Console( "Usage: joliedoc <filename> [ --internals ] [ --out-type 'html|md' ]")()
         } else {
             println@Console("Generating...")()
             internals = false
-            if ( #args == 2 && args[ 1 ] == "--internals" ) {
-                internals = true
-            } else if ( #args == 2 ) {
-                println@Console("Argument " + args[ 1 ] + " not recognized" )()
-                throw( Abort )
+            type = "html"
+            for ( i=0, i< #args, i++ ) {
+                if ( i == 0 ){
+                    rq.filename = args[ i ]
+                } else {
+                    if ( args[ i ] == "--internals" ){
+                        internals = true
+                    } else if ( args[ i ] == "--out-type" ){
+                        type = args[ ++i ]
+                    }
+
+                }
             }
-            rq.filename = args[ 0 ]
+
+            getServiceDirectory@File()( joliedoc_directory )
+            getFileSeparator@File()(sep)
+            // loading templates
+            readFile@File( { filename = joliedoc_directory + sep + "templates" + sep + type + sep + "overview-page-template.mustache" } )( ovh_template )
+            readFile@File( { filename = joliedoc_directory + sep + "templates" + sep + type + sep + "port-page-template.mustache" } )( port_page_template )
+            readFile@File( { filename = joliedoc_directory + sep + "templates" + sep + type + sep + "index-template.mustache" } )( index_template )
+            // loading partials
+            partials[0].name = "cardinality-template"
+            readFile@File( { filename = joliedoc_directory + sep + "templates" + sep + type + sep + "cardinality-template.mustache" } )( partials[0].template )
+            partials[1].name = "native-type-template"
+            readFile@File( { filename = joliedoc_directory + sep + "templates" + sep + type + sep + "native-type-template.mustache" } )( partials[1].template )
+            partials[2].name = "sub-type-template"
+            readFile@File( { filename = joliedoc_directory + sep + "templates" + sep + type + sep + "sub-type-template.mustache" } )( partials[2].template )
+            partials[3].name = "type-template"
+            readFile@File( { filename = joliedoc_directory + sep + "templates" + sep + type + sep + "type-template.mustache" } )( partials[3].template )
+            partials[4].name = "typeinline-template"
+            readFile@File( { filename = joliedoc_directory + sep + "templates" + sep + type + sep + "typeinline-template.mustache" } )( partials[4].template )
+            partials[5].name = "typelink-template"
+            readFile@File( { filename = joliedoc_directory + sep + "templates" + sep + type + sep + "typelink-template.mustache" } )( partials[5].template )
+
             getInputPortMetaData@MetaJolie( rq )( meta_description )
             __port_type = "input"
             _get_ports
@@ -451,7 +456,7 @@ service JolieDoc {
             getIndexPage@RenderDocPages( index_rq )( index )
 
             max_files = #files 
-            files[ max_files ].filename = "index.html"
+            files[ max_files ].filename = "index." + type
             files[ max_files ].html = index
 
             /* creating overview */
@@ -570,7 +575,7 @@ service JolieDoc {
             max_files = #files 
 
             getOverviewPage@RenderDocPages( ovh_template_req )( ovw )
-            files[ max_files ].filename = "Overview.html"
+            files[ max_files ].filename = "Overview." + type
             files[ max_files ].html = ovw
         }
 

diff --git a/tools/joliedoc/cardinality-template.html → ...plates/html/cardinality-template.mustache b/tools/joliedoc/cardinality-template.html → ...plates/html/cardinality-template.mustache
diff --git a/tools/joliedoc/index-template.html → ...oc/templates/html/index-template.mustache b/tools/joliedoc/index-template.html → ...oc/templates/html/index-template.mustache
diff --git a/tools/joliedoc/native-type-template.html → ...plates/html/native-type-template.mustache b/tools/joliedoc/native-type-template.html → ...plates/html/native-type-template.mustache
diff --git a/tools/joliedoc/overview-page-template.html → ...ates/html/overview-page-template.mustache b/tools/joliedoc/overview-page-template.html → ...ates/html/overview-page-template.mustache
diff --git a/tools/joliedoc/port-page-template.html → ...emplates/html/port-page-template.mustache b/tools/joliedoc/port-page-template.html → ...emplates/html/port-page-template.mustache
diff --git a/tools/joliedoc/sub-type-template.html → ...templates/html/sub-type-template.mustache b/tools/joliedoc/sub-type-template.html → ...templates/html/sub-type-template.mustache
diff --git a/tools/joliedoc/type-template.html → ...doc/templates/html/type-template.mustache b/tools/joliedoc/type-template.html → ...doc/templates/html/type-template.mustache
diff --git a/tools/joliedoc/typeinline-template.html → ...mplates/html/typeinline-template.mustache b/tools/joliedoc/typeinline-template.html → ...mplates/html/typeinline-template.mustache
diff --git a/tools/joliedoc/typelink-template.html → ...templates/html/typelink-template.mustache b/tools/joliedoc/typelink-template.html → ...templates/html/typelink-template.mustache
diff --git a/tools/joliedoc/templates/md/cardinality-template.mustache b/tools/joliedoc/templates/md/cardinality-template.mustache
@@ -0,0 +1 @@
+{{#cardinality}}[{{min}},{{infinite}}{{max}}]{{/cardinality}}
diff --git a/tools/joliedoc/templates/md/index-template.mustache b/tools/joliedoc/templates/md/index-template.mustache
@@ -0,0 +1,106 @@
+<html>
+
+<head>
+    <style>
+        body {
+            font-family: 'Courier New';
+            font-size: 14px;
+        }
+
+        .headertable {
+            width: 100%;
+            font-size: 30px;
+            padding: 10px;
+            border-bottom: 1px dotted #444;
+        }
+
+        .menutd {
+            width: 12%;
+            border-right: 1px dotted #444;
+            height: 1000px;
+        }
+
+        .bodytd {
+            width: 80%;
+        }
+
+        .bodytd object {
+            width: 100%;
+            height: 100vh;
+        }
+
+        .maintable {
+            width: 100%;
+        }
+
+        .menutitle {
+            font-weight: bold;
+            font-size: 20px;
+        }
+
+        .menutd a {
+            cursor: pointer;
+        }
+
+        .itemmenu {
+            text-align: center;
+            width: 100%;
+        }
+
+        .itemmenu a:hover {
+            color: #600;
+        }
+    </style>
+    <script>
+        function loadPage(page) {
+            document.getElementById("bodytd").innerHTML = '<object type=\"text/html\" data=\"' + page + '\"></object>';
+        }
+    </script>
+</head>
+
+<body>
+    <table class='headertable'>
+        <tr>
+            <td>Jolie Documentation:&nbsp;<b>{{filename}}</b></td>
+        </tr>
+    </table>
+    <table class='maintable'>
+        <tr>
+            <td valign='top' class='menutd'><br><br>
+                <table width='100%'>
+                    <tr>
+                        <td class='itemmenu'><a onclick='loadPage("Overview.html")'>OVERVIEW</a></td>
+                    </tr>
+                </table><br><br>
+                <table width='100%'>
+                    <tr>
+                        <td class='itemmenu menutitle'>input ports</td>
+                    </tr>
+                </table><br>
+                <table width='100%'>
+                    {{#ipitems}}
+                    <tr>
+                        <td class='itemmenu'><a onclick='loadPage("{{ipname}}IPort.html")'>{{ipname}}</a></td>
+                    </tr>
+                    {{/ipitems}}
+                </table><br><br>
+                <table width='100%'>
+                    <tr>
+                        <td class='itemmenu menutitle'>output ports</td>
+                    </tr>
+                </table><br>
+                <table width='100%'>
+                    {{#opitems}}
+                    <tr>
+                        <td class='itemmenu'><a onclick='loadPage("{{opname}}OPort.html")'>{{opname}}</a></td>
+                    </tr>
+                    {{/opitems}}
+                </table><br><br>
+            </td>
+            <td id='bodytd' class='bodytd'></td>
+        </tr>
+    </table>
+</body>
+<script>loadPage('Overview.html')</script>
+
+</html>
diff --git a/tools/joliedoc/templates/md/native-type-template.mustache b/tools/joliedoc/templates/md/native-type-template.mustache
@@ -0,0 +1 @@
+{{#string_type}}string{{/string_type}}{{#int_type}}int{{/int_type}}{{#double_type}}double{{/double_type}}{{#any_type}}any{{/any_type}}{{#void_type}}void{{/void_type}}{{#raw_type}}raw{{/raw_type}}{{#bool_type}}bool{{/bool_type}}{{#long_type}}long{{/long_type}}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{{#cardinality}}[{{min}},{{infinite}}{{max}}]{{/cardinality}}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{{#string_type}}string{{/string_type}}{{#int_type}}int{{/int_type}}{{#double_type}}double{{/double_type}}{{#any_type}}any{{/any_type}}{{#void_type}}void{{/void_type}}{{#raw_type}}raw{{/raw_type}}{{#bool_type}}bool{{/bool_type}}{{#long_type}}long{{/long_type}}