Merge pull request #721 from hexagontk/develop

Multiple versions site

.github/workflows/release.yml

@@ -27,21 +27,16 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           cache: gradle
 
-      - env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          export REMOTE="https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$GITHUB_REPOSITORY.git"
-          export GIT_COMMITTER_NAME="${GITHUB_ACTOR}"
-          export GIT_COMMITTER_EMAIL="project@hexagontk.com"
-          git remote set-url origin "$REMOTE"
-          ./gradlew build
-          ./gradlew -x build buildSite
-          ls -AlF site/build/site
+  # TODO
+  #      - env:
+  #          REPOSITORY_PASSWORD: ${{ secrets.HEXAGONTK_REPOSITORY_PASSWORD }}
+  #          REPOSITORY_USERNAME: ${{ secrets.HEXAGONTK_REPOSITORY_USERNAME }}
+  #          SIGNING_KEY: ${{ secrets.HEXAGONTK_SIGNING_KEY }}
+  #          SIGNING_PASSWORD: ${{ secrets.HEXAGONTK_SIGNING_PASSWORD }}
+  #        run: ./gradlew --no-daemon -x test release
 
-# TODO
-#      - env:
-#          REPOSITORY_PASSWORD: ${{ secrets.HEXAGONTK_REPOSITORY_PASSWORD }}
-#          REPOSITORY_USERNAME: ${{ secrets.HEXAGONTK_REPOSITORY_USERNAME }}
-#          SIGNING_KEY: ${{ secrets.HEXAGONTK_SIGNING_KEY }}
-#          SIGNING_PASSWORD: ${{ secrets.HEXAGONTK_SIGNING_PASSWORD }}
-#        run: ./gradlew --no-daemon -x test release
+  build_site:
+    uses: hexagontk/hexagon/.github/workflows/site.yml@develop
+    needs: publish
+    with:
+      options: -P pushSite=true

.github/workflows/release_branch.yml

@@ -27,26 +27,15 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           cache: gradle
 
-      - env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          export REMOTE="https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$GITHUB_REPOSITORY.git"
-          git remote set-url origin "$REMOTE"
-          git clone "$REMOTE" --branch gh-pages build/gh-pages
-          ./gradlew build
-          ./gradlew -x build buildSite
-          ls -AlF site/build/site
-
       - env:
           OSSRH_PASSWORD: ${{ secrets.OSSRH_PASSWORD }}
           OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
           SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
           SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
         run: ./gradlew --no-daemon -x test release
 
-      - run: |
-          cp -rf site/build/site/* build/gh-pages/
-          cd build/gh-pages
-          git add --all
-          git commit -m "Publishing to gh-pages"
-          git push origin gh-pages
+  push_site:
+    uses: hexagontk/hexagon/.github/workflows/site.yml@develop
+    needs: publish
+    with:
+      options: -P pushSite=true

.github/workflows/site.yml

@@ -27,6 +27,11 @@ on:
         description: Directory to check for build execution.
         default: site/build/site
 
+      options:
+        type: string
+        description: Extra options for the 'buildSite' target.
+        default: ''
+
 jobs:
   site:
     runs-on: ubuntu-latest
@@ -54,14 +59,13 @@ jobs:
           java-version: ${{ inputs.java }}
           cache: gradle
 
-      - run: ./gradlew --stacktrace build
-
       - env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           export GIT_COMMITTER_NAME="${GITHUB_ACTOR}"
           export GIT_COMMITTER_EMAIL="project@hexagontk.com"
-          ./gradlew --stacktrace -x build buildSite
+          ./gradlew --stacktrace build
+          ./gradlew --stacktrace -x build buildSite ${{ inputs.options }}
 
       - if: ${{ inputs.check_directory != '' }}
         run: ls -AlF "${{ inputs.check_directory }}"

.gitignore

@@ -40,6 +40,7 @@ hs_err_pid*
 # Other Tools
 kotlin-js-store/
 node_modules/
+.kotlin/
 .env
 
 # System Files

contributing.md

@@ -104,21 +104,21 @@ If you want to generate the documentation site, check the Hexagon's site module
 [GitHub Actions]: https://github.com/features/actions
 
 ## Major Release Checklist
-1. Release site's dependent projects (`hexagon_extra`)
-2. Publish their packages using the [Nexus Repository Manager]
-3. Merge Hexagon main project to `main` in GitHub
-4. Check the site deployment is OK ([https://hexagontk.com])
-5. Publish Hexagon modules using the [Nexus Repository Manager]
-6. Create a GitHub release
-7. Update starter repositories (Gradle and Maven ones)
-8. Update TFB benchmark
-9. Update example projects inside the organization
-10. Create a changelog to announce the release
-11. Publish changelog on:
+1. Replace documents' links: `/blob/main/` to `/blob/release/${version}/`
+2. Release site's dependent projects (`hexagon_extra`)
+3. Publish their packages using the [Nexus Repository Manager]
+4. Merge Hexagon main project to `main` in GitHub
+5. Check the site deployment is OK ([https://hexagontk.com])
+6. Publish Hexagon modules using the [Nexus Repository Manager]
+7. Create a GitHub release
+8. Update starter repositories (Gradle and Maven ones)
+9. Update TFB benchmark
+10. Update example projects inside the organization
+11. Create a changelog to announce the release
+12. Publish changelog on:
   * Dev.to
   * Reddit Kotlin
   * X (Twitter)
-  * Kotlin Weekly Newsletter
   * LinkedIn
   * Mailing lists (Awesome Kotlin, Kotlin Weekly)
 

core/README.md

@@ -33,7 +33,7 @@ application), you can import it with the following code:
 JVM information and other useful utilities. Includes basic program settings support at the [Jvm]
 object (like loading and retrieving system settings).
 
-[Jvm]: /api/core/com.hexagontk.core/-jvm
+[Jvm]: api/core/com.hexagontk.core/-jvm
 
 # Package com.hexagontk.core.logging
 Provides a logging management capabilities abstracting the application from logging libraries.
@@ -44,7 +44,7 @@ The following code block shows the most common use cases for the [Logger] class:
 
 By default, Hexagon uses the [System.Logger] class.
 
-[Logger]: /api/core/com.hexagontk.core.logging/-logger
+[Logger]: api/core/com.hexagontk.core.logging/-logger
 [System.Logger]: https://docs.oracle.com/javase/9/docs/api/java/lang/System.Logger.html
 
 # Package com.hexagontk.core.media

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.1-all.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

http/http/src/main/kotlin/com/hexagontk/http/model/HttpField.kt

@@ -2,6 +2,8 @@ package com.hexagontk.http.model
 
 /**
  * HTTP multi-value field. Used in headers, query parameters and form parameters.
+ *
+ * TODO Convert to name: String, value: Map<String, Any?>
  */
 interface HttpField {
     val name: String

http/http_client/README.md

@@ -20,7 +20,7 @@ Its main functionalities are:
 This module is not meant to be used directly. You should include an Adapter implementing this
 feature (as [http_client_jetty]) in order to create HTTP clients.
 
-[http_client_jetty]: /http_client_jetty
+[http_client_jetty]: http_client_jetty
 
 # Create an HTTP client
 You create an HTTP Client instance with default options as follows:
@@ -40,8 +40,8 @@ Check this code snippet to get a glimpse on how to send the most general request
 
 @code http/http_test/src/main/kotlin/com/hexagontk/http/test/examples/ClientTest.kt?genericRequest
 
-[Request]: /api/http/http/com.hexagontk.http.model/-http-request
-[Response]: /api/http/http/com.hexagontk.http.model/-http-response
+[Request]: api/http/http/com.hexagontk.http.model/-http-request
+[Response]: api/http/http/com.hexagontk.http.model/-http-response
 
 # Simple requests shortcuts
 There are utility methods to make the most common request in an easy way.
@@ -89,8 +89,8 @@ format.
 To set up client/server certificates, you need to include [SslSettings] in your [ClientSettings]. In
 the sections below you can see how to configure these parameters.
 
-[SslSettings]: /api/http/http/com.hexagontk.http/-ssl-settings
-[ClientSettings]: /api/http/http_client/com.hexagontk.http.client/-http-client-settings
+[SslSettings]: api/http/http/com.hexagontk.http/-ssl-settings
+[ClientSettings]: api/http/http_client/com.hexagontk.http.client/-http-client-settings
 
 ## Key Store
 This store holds the identity certificate, this certificate is presented to the server by the client
@@ -115,4 +115,4 @@ and client authenticated by the server). You can see a complete example below:
 # Package com.hexagontk.http.client
 This package holds the classes that define the HTTP client and its configuration settings.
 
-[http]: /http
+[http]: http

http/http_client_java/README.md

@@ -2,7 +2,7 @@
 # Module http_client_java
 [http_client] implementation using the [Java HTTP Client] classes.
 
-[http_client]: /http_client
+[http_client]: http_client
 [Java HTTP Client]: https://docs.oracle.com/en/java/javase/21/docs/api/java.net.http/java/net/http/HttpClient.html
 
 ### Install the Dependency

http/http_client_jetty/README.md

@@ -2,7 +2,7 @@
 # Module http_client_jetty
 [http_client] implementation using the [Jetty HTTP Client] library.
 
-[http_client]: /http_client
+[http_client]: http_client
 [Jetty HTTP Client]: https://jetty.org/docs/jetty/12/programming-guide
 
 ### Install the Dependency

http/http_client_jetty_ws/README.md

@@ -6,7 +6,7 @@
 >
 > <sup>WebSockets are not supported on GraalVM native images at the moment.</sup>
 
-[http_client]: /http_client
+[http_client]: http_client
 [Jetty HTTP Client]: https://jetty.org/docs/jetty/12/programming-guide
 
 ### Install the Dependency

http/http_handlers/README.md

@@ -10,7 +10,7 @@ handlers.
 This module is not meant to be used directly. You should include and Adapter implementing this
 feature (as [http_server_jetty]) in order to create an HTTP server.
 
-[http_server_jetty]: /http_server_jetty
+[http_server_jetty]: http_server_jetty
 
 # Chaining changes
 The response can be modified chaining `send` calls (or its utility methods). However, If calls are
@@ -77,17 +77,17 @@ methods.
 
 @code http/http_test/src/main/kotlin/com/hexagontk/http/test/examples/SamplesTest.kt?serverCreation
 
-[server settings]: /api/http/http_server/com.hexagontk.http.server/-http-server-settings
-[handlers section]: /http_server/#handlers
-[start()]: /api/http/http_server/com.hexagontk.http.server/-http-server
-[stop()]: /api/http/http_server/com.hexagontk.http.server/-http-server
+[server settings]: api/http/http_server/com.hexagontk.http.server/-http-server-settings
+[handlers section]: http_server/#handlers
+[start()]: api/http/http_server/com.hexagontk.http.server/-http-server
+[stop()]: api/http/http_server/com.hexagontk.http.server/-http-server
 
 ## Servlet Web server
 There is a special server adapter for running inside Servlet Containers. To use it you should import
 the Servlet HTTP Server Adapter into your project. Check the [http_server_servlet] module for more
 information.
 
-[http_server_servlet]: /http_server_servlet
+[http_server_servlet]: http_server_servlet
 
 # HTTP Context
 These are the events that the handlers handle (they are also called HTTP calls or just calls along
@@ -103,7 +103,7 @@ full list of methods. This sample code illustrates the usage:
 
 @code http/http_test/src/main/kotlin/com/hexagontk/http/test/examples/SamplesTest.kt?callbackCall
 
-[API documentation]: /api/http/http_handlers/com.hexagontk.http.handlers/-http-context
+[API documentation]: api/http/http_handlers/com.hexagontk.http.handlers/-http-context
 
 # Handlers
 The main building blocks of Hexagon HTTP services are a set of handlers. A handler is made up of two
@@ -139,7 +139,7 @@ Check the next snippet for Handlers usage examples:
 
 @code http/http_test/src/main/kotlin/com/hexagontk/http/test/examples/SamplesTest.kt?routesCreation
 
-[next]: /api/http/http_handlers/com.hexagontk.http.handlers/-http-context
+[next]: api/http/http_handlers/com.hexagontk.http.handlers/-http-context
 
 <!-- TODO Start document review -->
 
@@ -157,7 +157,7 @@ the following fields:
 
 It yields true if all the supplied fields matches a call context.
 
-[HttpPredicate]: /api/http/http_handlers/com.hexagontk.http.handlers/-http-predicate
+[HttpPredicate]: api/http/http_handlers/com.hexagontk.http.handlers/-http-predicate
 
 ## Path Patterns
 Patterns to match requests paths. They can have:
@@ -294,15 +294,15 @@ Check the next example for details:
 The media types of static files are computed from the file extension using the utility methods of
 the [com.hexagontk.core.media] package.
 
-[com.hexagontk.core.media]: /api/core/com.hexagontk.core.media
+[com.hexagontk.core.media]: api/core/com.hexagontk.core.media
 
 # CORS
 CORS behaviour can be different depending on the path. You can attach different [CORS Callbacks] to
 different handlers. Check the [CorsCallback][CORS Callbacks] class for more details.
 
 @code http/http_test/src/main/kotlin/com/hexagontk/http/test/examples/CorsTest.kt?cors
 
-[CORS Callbacks]: /api/http/http_server/com.hexagontk.http.server.callbacks/-cors-callback
+[CORS Callbacks]: api/http/http_server/com.hexagontk.http.server.callbacks/-cors-callback
 
 # HTTPS
 It is possible to start a secure server enabling HTTPS. For this, you have to provide a server
@@ -327,14 +327,14 @@ Below you can find a simple example to set up an HTTPS server and client with mu
 
 @code http/http_test/src/main/kotlin/com/hexagontk/http/test/examples/HttpsTest.kt?https
 
-[SslSettings]: /api/http/http/com.hexagontk.http/-ssl-settings
+[SslSettings]: api/http/http/com.hexagontk.http/-ssl-settings
 [HTTP/2]: https://en.wikipedia.org/wiki/HTTP/2
 [ALPN]: https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation
 [Gradle]: https://gradle.org
-[create sample certificates]: /gradle/#certificates
+[create sample certificates]: gradle/#certificates
 [mutual TLS]: https://en.wikipedia.org/wiki/Mutual_authentication
-[SslSettings.clientAuth]: /api/http/http/com.hexagontk.http/-ssl-settings
-[Request.certificateChain]: /api/http/http/com.hexagontk.http.model/-http-request
+[SslSettings.clientAuth]: api/http/http/com.hexagontk.http/-ssl-settings
+[Request.certificateChain]: api/http/http/com.hexagontk.http.model/-http-request
 
 # WebSockets
 A Web Socket is an HTTP(S) connection made with the GET method and the `upgrade: websocket` and
@@ -405,4 +405,4 @@ Classes to model server HTTP messages (requests and responses). Built on top of
 # Package com.hexagontk.http.model.ws
 Classes to model server HTTP messages (requests and responses). Built on top of the [http] module.
 
-[http]: /http
+[http]: http