Move Jelly-JVM documentation into this repository (#98)

Jelly-JVM is independently versioned from the Jelly protocol, so it makes no sense to host it together with the specification.

This PR will be followed by a set of updates in the main doc repo.

.github/workflows/release.yml

@@ -67,3 +67,34 @@ jobs:
           name: "${{ env.GITHUB_REF_NAME }}"
           artifacts: 'jena/target/scala-*/*-plugin.jar,rdf4j/target/scala-*/*-plugin.jar'
           generateReleaseNotes: true
+
+  publish-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: pip
+          cache-dependency-path: 'docs/requirements.txt'
+
+      - name: Install dependencies
+        working-directory: ./docs
+        run: pip install -r requirements.txt
+
+      - name: Deploy site
+        run: |
+          export TAG='${{ env.GITHUB_REF_NAME }}'
+          git fetch origin gh-pages --depth=1
+          git config user.name ci-bot
+          git config user.email [email protected]
+          if [[ $TAG == v* ]] ; then
+            V_MAJOR=`echo ${TAG#v} | awk -F '.' '{print $1}'`
+            V_MINOR=`echo ${TAG#v} | awk -F '.' '{print $2}'`
+            mike deploy --push --update-aliases "${V_MAJOR}.${V_MINOR}.x" stable "${TAG#v}"
+          else
+            mike deploy --push --update-aliases dev latest
+          fi

.github/workflows/test-docs.yml

@@ -0,0 +1,32 @@
+name: Test documentation compilation
+
+on:
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: pip
+          cache-dependency-path: 'docs/requirements.txt'
+
+      - name: Install dependencies
+        working-directory: ./docs
+        run: pip install -r requirements.txt
+
+      - name: Build documentation
+        working-directory: ./docs
+        run: |
+          export TAG='main'
+          mkdocs build -s

docs/.gitignore

@@ -0,0 +1,3 @@
+/venv
+/site
+/__pycache__

docs/README.md

@@ -0,0 +1,3 @@
+This directory houses the sources for the documentation displayed on the [Jelly website](https://jelly-rdf.github.io/jelly-jvm).
+
+The actual documentation files are in the `docs` subdirectory.

docs/docs/dev/implementing.md

@@ -0,0 +1,22 @@
+# Developer guide – implementing conversions for other libraries
+
+Currently converters for the two most popular RDF JVM libraries are implemented – RDF4J and Jena. But it is possible to implement your own converters and adapt the Jelly serialization code to any RDF library with little effort.
+
+To do this, you will need to implement three traits (interfaces in Java) from the `jelly-core` module: `ProtoEncoder`, `ProtoDecoderConverter`, and `ConverterFactory`.
+
+- **ProtoEncoder (serialization)**
+    - `get*` methods deconstruct triple statements, quad statements, and quoted triples (RDF-star). You can make them `inline`.
+    - `nodeToProto` and `graphToProto` should translate into Jelly's representation all possible variations of RDF terms in the SPO and G positions, respectively.
+    - Example implementation for Jena: [JenaProtoEncoder](https://github.com/Jelly-RDF/jelly-jvm/blob/main/jena/src/main/scala/eu/ostrzyciel/jelly/convert/jena/JenaProtoEncoder.scala)
+    - You can skip implementing this trait if you don't need serialization.
+    - You can also skip implementing some methods (make them throw an exception or return null) if, for example, you don't want to work with quads or RDF-start.
+
+- **ProtoDecoderConverter (deserialization)**
+    - The `make*` methods should construct new RDF terms and statements. You can make them `inline`.
+    - Example implementation for Jena: [JenaDecoderConverter](https://github.com/Jelly-RDF/jelly-jvm/blob/main/jena/src/main/scala/eu/ostrzyciel/jelly/convert/jena/JenaDecoderConverter.scala)
+    - You can skip implementing this trait if you don't need deserialization.
+    - You can also skip implementing some methods (make them throw an exception or return null) if, for example, you don't want to work with quads or RDF-start.
+
+- **ConverterFactory** – wrapper that allows other modules to use your converter.
+    - The methods should just return new instances of your `ProtoEncoder` and `ProtoDecoderConverter` implementations.
+    - Example for Jena: [JenaConverterFactory](https://github.com/Jelly-RDF/jelly-jvm/blob/main/jena/src/main/scala/eu/ostrzyciel/jelly/convert/jena/JenaConverterFactory.scala)

docs/docs/dev/releases.md

@@ -0,0 +1,19 @@
+# Developer guide – releases
+
+## Full (versioned) releases
+
+Full (versioned) releases are created manually and follow the [Semantic Versioning](https://semver.org/) scheme for binary compatibility.
+
+To create a new tagged release (example for version 1.2.3):
+```sh
+$ git checkout main
+$ git pull
+$ git tag v1.2.3
+$ git push origin v1.2.3
+```
+
+The rest (packaging and release creation) will be handled automatically by the CI. The release will be pushed to Maven Central.
+
+## Snapshot releases
+
+Snapshot releases are triggered automatically by commits in the `main` branch. Snapshots are pushed to the Sonatype snapshot repository.

docs/docs/getting-started-devs.md

@@ -0,0 +1,5 @@
+# Jelly-JVM – getting started for developers
+
+*If you don't want to code anything and only use Jelly with your Apache Jena/RDF4J application, see [the dedicated guide](getting-started-plugins.md) about using Jelly-JVM as a plugin.*
+
+TODO: for 

docs/docs/getting-started-plugins.md

@@ -0,0 +1,41 @@
+# Jelly-JVM – getting started with Jena/RDF4J plugins
+
+This guide explains how to use Jelly-JVM with Apache Jena or RDF4J as a plugin, **without writing a single line of code**. Jelly-JVM provides plugin JARs that you can simply drop in the appropriate directory to get Jelly format support in your application.
+
+## Installation
+
+### Apache Jena, Apache Jena Fuseki
+
+You can simply add Jelly format support to [Apache Jena](https://jena.apache.org/index.html) or [Apacha Jena Fuseki](https://jena.apache.org/documentation/fuseki2/index.html) with Jelly's plugin JAR.
+
+- First, download the plugin JAR. You can download the **[latest stable version from here](https://github.com/Jelly-RDF/jelly-jvm/releases/latest/download/jelly-jena-plugin.jar)**, or you can go the the [releases page](https://github.com/Jelly-RDF/jelly-jvm/releases) on GitHub to download a specific version of the `jelly-jena-plugin.jar` file.
+    - Note that the Jelly version must be compatible with your Apache Jena version. Consult the [compatibility table](index.md#compatibility).
+- Place the file in your classpath:
+    - For Apache Jena Fuseki, simply place the file in `$FUSEKI_BASE/extra/` directory. `$FUSEKI_BASE` is the directory usually called `run` where you have files such as `config.ttl` and `shiro.ini`. You will most likely need to create the `extra` directory yourself.
+    - For Apache Jena, place the file in the `lib/` directory of your Jena installation.
+    - For other applications, consult the manual of the application.
+- You can now use Jelly format for parsing, serialization, and streaming serialization in your Jena application.
+
+### Eclipse RDF4J
+
+You can simply add Jelly format support to an application based on RDF4J with Jelly's plugin JAR.
+
+- First, download the plugin JAR. You can download the **[latest stable version from here](https://github.com/Jelly-RDF/jelly-jvm/releases/latest/download/jelly-rdf4j-plugin.jar)**, or you can go the the [releases page](https://github.com/Jelly-RDF/jelly-jvm/releases) on GitHub to download a specific version of the `jelly-rdf4j-plugin.jar` file.
+    - Note that the Jelly version must be compatible with your RDF4J version. Consult the [compatibility table](index.md#compatibility).
+- Place the file in your classpath. Consult the manual of your application for the exact location.
+- You can now use Jelly format for parsing, serialization, and streaming serialization in your RDF4J application.
+
+## Supported features
+
+The Jelly-JVM plugin JARs provide the following features:
+
+- Full support for parsing and serialization of RDF data (triples and quads) in the Jelly format.
+    - In Apache Jena also the stream serialization is supported.
+- Recognizing the `.jelly` file extension.
+- Recognizing the `application/x-jelly-rdf` media type.
+
+The Jelly format is registered under the name `jelly` in the RDF libraries, so you can use it in the same way as other formats like Turtle, RDF/XML, or JSON-LD.
+
+## See also
+
+- **[Getting started for developers](getting-started-devs.md)** – if you want to get your hands dirty with code and get more features out of Jelly.

docs/docs/index.md

@@ -0,0 +1,67 @@
+# Jelly-JVM
+
+**Jelly-JVM** is an implementation of the Jelly serialization format and the gRPC streaming protocol for the Java Virtual Machine (JVM), written in Scala 3. The supported RDF libraries are [Apache Jena](https://jena.apache.org/) and [Eclipse RDF4J](https://rdf4j.org/).
+
+This collection of libraries aims to provide the full stack of utilities for fast and scalable RDF streaming with the [Jelly protocol]({{ proto_link( 'specification' ) }}).
+
+!!! tip "Getting started with plugins – no code required"
+
+    See the **[Getting started guide](getting-started-plugins.md)** for a quick way to use Jelly with your Apache Jena or RDF4J application without writing any code.
+
+!!! tip "Getting started for developers"
+
+    If you want to use the full feature set of Jelly-JVM in your code, see the **[Getting started guide](getting-started-devs.md)** for developers.
+
+TODO: versioning – point to the version selector in the navbar
+
+{{ jvm_version() }}
+
+{{ proto_version() }} 
+
+## Library modules
+
+The implementation is split into a few modules that can be used separately:
+
+- `jelly-core` – implementation of the [Jelly serialization format]({{ proto_link( 'specification/serialization' ) }}) (using the [scalapb](https://scalapb.github.io/) library), along with generic utilities for converting the deserialized RDF data to/from the representations of RDF libraries (like Apache Jena or RDF4J). 
+    - [![jelly-core Scala version support](https://index.scala-lang.org/jelly-rdf/jelly-jvm/jelly-core/latest.svg)](https://index.scala-lang.org/jelly-rdf/jelly-jvm/jelly-core) [![javadoc](https://javadoc.io/badge2/eu.ostrzyciel.jelly/jelly-core_3/javadoc.svg)](https://javadoc.io/doc/eu.ostrzyciel.jelly/jelly-core_3) 
+
+- `jelly-jena` – conversions and interop code for the [Apache Jena](https://jena.apache.org/) library.
+    - [![jelly-jena Scala version support](https://index.scala-lang.org/jelly-rdf/jelly-jvm/jelly-jena/latest.svg)](https://index.scala-lang.org/jelly-rdf/jelly-jvm/jelly-jena) [![javadoc](https://javadoc.io/badge2/eu.ostrzyciel.jelly/jelly-jena_3/javadoc.svg)](https://javadoc.io/doc/eu.ostrzyciel.jelly/jelly-jena_3)
+
+- `jelly-rdf4j` – conversions and interop code for the [RDF4J](https://rdf4j.org/) library.
+    - [![jelly-rdf4j Scala version support](https://index.scala-lang.org/jelly-rdf/jelly-jvm/jelly-rdf4j/latest.svg)](https://index.scala-lang.org/jelly-rdf/jelly-jvm/jelly-rdf4j) [![javadoc](https://javadoc.io/badge2/eu.ostrzyciel.jelly/jelly-rdf4j_3/javadoc.svg)](https://javadoc.io/doc/eu.ostrzyciel.jelly/jelly-rdf4j_3)
+
+- `jelly-stream` – utilities for building [Reactive Streams](https://www.reactive-streams.org/) of RDF data (based on Pekko Streams). Useful for integrating with gRPC or other streaming protocols (e.g., Kafka, MQTT).
+    - [![jelly-stream Scala version support](https://index.scala-lang.org/jelly-rdf/jelly-jvm/jelly-stream/latest.svg)](https://index.scala-lang.org/jelly-rdf/jelly-jvm/jelly-stream) [![javadoc](https://javadoc.io/badge2/eu.ostrzyciel.jelly/jelly-stream_3/javadoc.svg)](https://javadoc.io/doc/eu.ostrzyciel.jelly/jelly-stream_3)
+
+- `jelly-grpc` – implementation of a gRPC client and server for the [Jelly gRPC streaming protocol]({{ proto_link( 'specification/streaming' ) }}).
+    - [![jelly-grpc Scala version support](https://index.scala-lang.org/jelly-rdf/jelly-jvm/jelly-grpc/latest.svg)](https://index.scala-lang.org/jelly-rdf/jelly-jvm/jelly-grpc) [![javadoc](https://javadoc.io/badge2/eu.ostrzyciel.jelly/jelly-grpc_3/javadoc.svg)](https://javadoc.io/doc/eu.ostrzyciel.jelly/jelly-grpc_3)
+
+## TODO: PLUGIN JARS
+
+## Compatibility
+
+The Jelly-JVM implementation is compatible with Java 11 and newer. Java 11, 17, and 21 are tested in CI and are guaranteed to work. Jelly is built with [Scala 3 LTS releases](https://www.scala-lang.org/blog/2022/08/17/long-term-compatibility-plans.html).
+
+The following table shows the compatibility of the Jelly-JVM implementation with other libraries:
+
+| Jelly | Scala       | Java | RDF4J | Apache Jena | Apache Pekko |
+| ----- | ----------- | ---- | ----- | ----------- | ------------ |
+| **1.0.x (current)** | 3.3.x (LTS) | 11+  | 4.x.y | 4.x.y       | 1.0.x        |
+
+## Documentation
+
+Below is a list of all documentation pages about Jelly-JVM. You can also browse the Javadoc using the badges in the module list above. The documentation uses examples written in Scala, but the libraries can be used from Java as well.
+
+- [Getting started with Jena/RDF4J plugins](getting-started-plugins.md) – how to use Jelly-JVM as a plugin for Apache Jena or RDF4J, without writing any code.
+- [Getting started for developers](getting-started-devs.md) – how to use Jelly-JVM in code.
+- User guide
+    - [Apache Jena integration](user/jena.md)
+    - [RDF4J integration](user/rdf4j.md)
+    - [Reactive streaming](user/reactive.md)
+    - [gRPC](user/grpc.md)
+    - [Userful utilities](user/utilities.md)
+- Developer guide
+    - [Releases](dev/releases.md)
+    - [Implementing Jelly for other libraries](dev/implementing.md)
+- [Main Jelly website]({{ proto_link( '' ) }}) – including the Jelly protocol specification and explanation of the the various stream types.

docs/docs/user/grpc.md

@@ -0,0 +1,3 @@
+# User guide – gRPC
+
+## Example – gRPC pub/sub

docs/docs/user/jena.md

@@ -0,0 +1,5 @@
+...
+
+If you just want to use Jelly with your Apache Jena / Apache Jena Fuseki, you can use the Jelly-JVM plugin JAR. See the **[dedicated guide](../getting-started-plugins.md#apache-jena-apache-jena-fuseki)** for more information.
+
+

docs/docs/user/rdf4j.md

@@ -0,0 +1,4 @@
+...
+
+If you just want to use Jelly with your RDF4J application, you can use the Jelly-JVM plugin JAR. See the **[dedicated guide](../getting-started-plugins.md#eclipse-rdf4j)** for more information.
+

docs/docs/user/reactive.md

@@ -0,0 +1,11 @@
+# User guide – reactive streaming
+
+TODO
+
+### Example: streaming with Kafka
+
+## Byte streams
+
+TODO
+
+(referenced by specification/serialization.md)

docs/docs/user/utilities.md

@@ -0,0 +1,3 @@
+# Useful utilities
+
+TODO: all utilities defined in `core`, including obtaining RDF-STaX annotations (describe its potential uses – external metadata, etc. – in the docs.) and constructing logical types from RDF-STaX IRIs.

docs/main.py

@@ -0,0 +1,61 @@
+# See: https://mkdocs-macros-plugin.readthedocs.io/en/latest
+
+import os
+import subprocess
+
+
+def define_env(env):
+
+    @env.macro
+    def jvm_version():
+        tag = os.environ.get('TAG', 'dev')
+        if tag == 'dev':
+            print('Warning: TAG env var is not set, using dev as default')
+            return tag
+        elif tag == 'main':
+            return 'dev'
+        else:
+            return tag.replace('v', '')
+
+
+    @env.macro
+    def git_tag():
+        return os.environ.get('TAG', 'main')
+
+
+    @env.macro
+    def git_link(file: str):
+        tag = git_tag()
+        return f'https://github.com/Jelly-RDF/jelly-jvm/blob/{tag}/{file}'
+
+
+    @env.macro
+    def proto_version():
+        if jvm_version() == 'dev':
+            return 'dev'
+
+        tag = subprocess.run(
+            ['git', 'describe', '--tags', '--abbrev=0'],
+            cwd='../core/src/main/protobuf_shared',
+            check=True,
+            capture_output=True,
+        ).stdout.decode().strip()
+        return tag.replace('v', '')
+
+
+    @env.macro
+    def proto_link(page: str):
+        version = proto_version()
+        return f'https://jelly-rdf.github.io/{version}/{page}'
+
+
+    def transform_nav_item(item):
+        if list(item.values())[0] == 'https://jelly-rdf.github.io/':
+            return {list(item.keys())[0]: proto_link('')}
+        return item
+
+
+    env.conf['nav'] = [
+        transform_nav_item(item)
+        for item in env.conf['nav']
+    ]