ci: Publish docs on release (#491)

zio · Nov 10, 2024 · 22d6e6c · 22d6e6c
1 parent ff7b394
commit 22d6e6c
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 108 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -77,6 +77,49 @@ jobs:
             echo $COMMAND
             eval $COMMAND
           fi
+  release-and-notify-docs:
+    name: Release and Notify Docs
+    runs-on: ubuntu-latest
+    continue-on-error: false
+    needs: [ 'publish-artifacts' ]
+    if: ${{ ((github.event_name == 'release') && (github.event.action == 'published')) || (github.event_name == 'workflow_dispatch') }}
+    strategy:
+      matrix:
+        java: [ '11' ]
+    steps:
+      - uses: 7mind/github-env@main
+        with:
+          java-version: ${{ matrix.java }}
+      - name: Setup NodeJs
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          registry-url: https://registry.npmjs.org
+      - name: Update Documentation
+        run: |
+          awk '/<!--- docs:start --->/,/<!--- docs:end --->/' README.md >> docs/index.md
+          sed -i '/<!--- docs:start --->/d' docs/index.md
+          sed -i '/<!--- docs:end --->/d' docs/index.md
+      - name: Publish Docs to NPM Registry
+        run: sbt docs/publishToNpm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Notify the main repo about the new release of docs package
+        run: |
+          PACKAGE_NAME=$(cat docs/package.json | grep '"name"' | awk -F'"' '{print $4}')
+          PACKAGE_VERSION=$(npm view $PACKAGE_NAME version)
+          curl -L \
+            -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: token ${{ secrets.PAT_TOKEN }}"\
+              https://api.github.com/repos/zio/zio/dispatches \
+              -d '{
+                    "event_type":"update-docs",
+                    "client_payload":{
+                      "package_name":"'"${PACKAGE_NAME}"'",
+                      "package_version": "'"${PACKAGE_VERSION}"'"
+                    }
+                  }'
   all-good:
     if: always()
     runs-on: ubuntu-latest

diff --git a/README.md b/README.md
@@ -13,6 +13,7 @@
 
 ---
 
+<!--- docs:start --->
 # izumi-reflect
 
 > @quote: Looks a bit similar to TypeTag
@@ -74,6 +75,7 @@ Other useful system properties are:
 
 - [`izumi.reflect.rtti.optimized.equals`](https://javadoc.io/doc/dev.zio/izumi-reflect_2.13/latest/izumi/reflect/DebugProperties$.html#izumi.reflect.rtti.optimized.equals:String(%22izumi.reflect.rtti.optimized.equals%22))
 - [`izumi.reflect.rtti.cache.compile`](https://javadoc.io/doc/dev.zio/izumi-reflect_2.13/latest/izumi/reflect/DebugProperties$.html#izumi.reflect.rtti.cache.compile:String(%22izumi.reflect.rtti.cache.compile%22))
+<!--- docs:end --->
 
 ## Build
 
@@ -105,6 +107,7 @@ Likewise with Scala 3:
 
 In Intellij, you may also set Scala version by changing the option `sbt -> sbt settings -> Open cross-compiled projects Scala 3 / Scala 2 projects as:`
 
+<!--- docs:start --->
 # Talks
 
 * [Kit Langton — Scala 3 Macro Fun (Open Source Hackery)](https://www.youtube.com/watch?v=wsLhjqCKZuU)
@@ -133,3 +136,4 @@ In Intellij, you may also set Scala version by changing the option `sbt -> sbt s
 
 [Stage]: https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg
 [Stage-Page]: https://github.com/zio/zio/wiki/Project-Stages
+<!--- docs:end --->
diff --git a/docs/index.md b/docs/index.md
@@ -4,111 +4,3 @@ title: "Introduction to izumi-reflect"
 sidebar_label: "izumi-reflect"
 ---
 
----
-
-<p align="center">
-  <a href="https://www.buymeacoffee.com/7mind"><img src="https://bmc-cdn.nyc3.digitaloceanspaces.com/BMC-button-images/custom_images/orange_img.png" alt="Izumi"/></a>
-</p>
-
----
-
-> @quote: Looks a bit similar to TypeTag
-
-`izumi-reflect` is a fast, lightweight, portable and efficient alternative for `TypeTag` from `scala-reflect`. `izumi-reflect` is a lightweight model of Scala type system and provides a simulator of the important parts of the Scala typechecker.
-
-@PROJECT_BADGES@
-
-## Why `izumi-reflect`?
-
-1. `izumi-reflect` compiles faster, runs a lot faster than `scala-reflect` and is fully immutable and [thread-safe](https://github.com/scala/bug/issues/10766),
-2. `izumi-reflect` supports Scala 2.11, 2.12, 2.13 and **Scala 3**,
-3. `izumi-reflect` supports Scala.js and Scala Native,
-4. `izumi-reflect` works well with [GraalVM Native Image](https://www.graalvm.org/reference-manual/native-image/),
-5. `izumi-reflect` allows you to obtain tags for unapplied type constructors (`F[_]`) and combine them at runtime.
-
-## Limitations
-
-`izumi-reflect` model of the Scala type system is not 100% precise, but "good enough" for the vast majority of the usecases.
-
-Known limitations are:
-
-1. Recursive type bounds (F-bounded types) are not preserved and may produce false positives,
-2. Existential types, both written with wildcards and `forSome` may produce unexpected results, the support is limited,
-3. Path-Dependent Types are based on variable names and may cause unexpected results when variables with different names have the same type or vice-versa (vs. Scala compiler)
-4. This-Types such as `X.this.type` are ignored and identical to `X`
-5. `izumi-reflect` is less powerful than `scala-reflect`: it does not preserve fields and methods when it's not necessary for equality and subtype checks, it does not preserve code trees, internal compiler data structures, etc.
-6. There are some optimizations in place which reduce correctness, namely: subtype check for `scala.Matchable` will always return true, no distinction is made between `scala.Any` and `scala.AnyRef`.
-7. Lower bounds are not preserved in abstract higher-kinded type members which may produce false comparisons.
-
-## Installation
-
-In order to use this library, we need to add the following line in our `build.sbt` file:
-
-```scala
-libraryDependencies += "dev.zio" %% "izumi-reflect" % "@VERSION@"
-```
-
-## Debugging
-
-Set [`-Dizumi.reflect.debug.macro.rtti=true`](https://javadoc.io/doc/dev.zio/izumi-reflect_2.13/latest/izumi/reflect/DebugProperties$.html#izumi.reflect.debug.macro.rtti:String(%22izumi.reflect.debug.macro.rtti%22)) to enable debug output during compilation when tags are constructed and at runtime when they are compared.
-
-```shell
-sbt -Dizumi.reflect.debug.macro.rtti=true
-```
-
-To see debug output when compiling in Intellij, add the above flag to `VM options` in [Preferences -> Build, Execution, Deployment -> Compiler -> Scala Compiler -> Scala Compile Server](jetbrains://idea/settings?name=Build%2C+Execution%2C+Deployment--Compiler--Scala+Compiler--Scala+Compile+Server)
-
-You may also set it in `.jvmopts` file during development. (`.jvmopts` properties will not apply to Intellij compile server, only to sbt)
-
-Set `-Dizumi.reflect.debug.macro.rtti.assertions=true` to enable additional assertions.
-
-Other useful system properties are:
-
-- [`izumi.reflect.rtti.optimized.equals`](https://javadoc.io/doc/dev.zio/izumi-reflect_2.13/latest/izumi/reflect/DebugProperties$.html#izumi.reflect.rtti.optimized.equals:String(%22izumi.reflect.rtti.optimized.equals%22))
-- [`izumi.reflect.rtti.cache.compile`](https://javadoc.io/doc/dev.zio/izumi-reflect_2.13/latest/izumi/reflect/DebugProperties$.html#izumi.reflect.rtti.cache.compile:String(%22izumi.reflect.rtti.cache.compile%22))
-
-## Build
-
-`build.sbt` is generated by [sbtgen](https://github.com/7mind/sbtgen). During development you may not want to mess with ScalaJS and ScalaNative, you may generate a pure-JVM Scala project:
-
-```bash
-./sbtgen.sc
-```
-
-Once you finished tinkering with the code you may want to generate full project and test it for all the platforms:
-
-```bash
-./sbtgen.sc --js --native
-sbt +test
-```
-
-To develop using Scala 2 invoke sbtgen with a scala version argument:
-
-```bash
-./sbtgen.sc 2 // 2.13
-./sbtgen.sc 2.12 // 2.12
-```
-
-Likewise with Scala 3:
-
-```bash
-./sbtgen.sc 3
-```
-
-In Intellij, you may also set Scala version by changing the option `sbt -> sbt settings -> Open cross-compiled projects Scala 3 / Scala 2 projects as:`
-
-## See also
-
-### [`gzoller/scala-reflection`](https://github.com/gzoller/scala-reflection)
-
-* Scala 3 only
-* No support for subtype checks
-* Requires compiler plugin
-* Type lambdas are not supported
-* Preserves field information
-
-### [`airframe-surface`](https://wvlet.org/airframe/docs/airframe-surface)
-
-* Scala 2 and Scala 3
-* No support for subtype checks
-* Preserves field information