Documentation build system

Pages and tools to build a public website for the specs. Includes documentation for the existing schema.

.github/workflows/pages.yml

@@ -0,0 +1,51 @@
+name: Build Pages
+on:
+    push:
+        branches:
+            - main
+            - docs-setup
+    workflow_dispatch:
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+jobs:
+  pages:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Setup
+        run: |
+            sudo apt update -q
+            sudo apt install -yy python3 python3-pip graphviz
+            pip install -r tools/requirements.txt
+      -
+        name: Docs
+        run: |
+            ./tools/schema-merge.py
+            ./tools/mkdocs build -d site
+      -
+        name: Setup Pages
+        uses: actions/configure-pages@v4
+      -
+        name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+            path: 'site'
+      -
+        name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3
+

.github/workflows/test-schema.yml

@@ -8,17 +8,19 @@ jobs:
     steps:
       -
         name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       -
         name: Setup
         run: |
             sudo apt update -q
-            sudo apt install -yy python3 python3-pip
+            sudo apt install -yy python3 python3-pip graphviz
+            pip install -r tools/requirements.txt
       -
         name: Build
         run: |
             ./tools/schema-merge.py
+            ./tools/mkdocs build -d site
       -
         name: Validate
         run: |
-            ./tools/schema-validate.py
+            ./tools/schema-validate.py --html site/specs

.gitignore

@@ -0,0 +1,2 @@
+docs/lottie.schema.json
+site/

docs/editing/extensions.md

@@ -0,0 +1,179 @@
+# Markdown Extensions
+
+This documentation comes with several markdown extensions that allow
+interactive elements and data pulled from the schema.
+
+## Schema Integration
+
+### `schema_string`
+
+Using a reference to a value in the JSON schema (without `$defs`) will embed that string
+into the markdown text.
+
+Example:
+
+```
+{schema_string:shapes/graphic-element/description}
+```
+
+Output:
+
+{schema_string:shapes/graphic-element/description}
+
+### `schema_link`
+
+Link to the relevant section in the formatted schema.
+
+Example:
+
+```
+{schema_link:shapes/ellipse}
+```
+
+Output:
+
+{schema_link:shapes/ellipse}
+
+### `schema_subtype_table`
+
+Used to list all the `ty` values for Layer / Shape etc.
+
+
+Example:
+
+```
+{schema_subtype_table:layers/all-layers:ty}
+```
+
+Output:
+
+{schema_subtype_table:layers/all-layers:ty}
+
+### `schema_object`
+
+Embeds a property table from the schema.
+
+Example:
+
+```
+{schema_object:shapes/ellipse}
+```
+
+Output:
+
+{schema_object:shapes/ellipse}
+
+### `schema_enum`
+
+Same as `schema_object` but for enumerations.
+
+Example:
+
+```
+{schema_enum:fill-rule}
+```
+
+Output:
+
+{schema_enum:fill-rule}
+
+### `schema_inheritance`
+
+Shows the inheritance diagram for an object type.
+
+Example:
+
+```
+{schema_inheritance:shapes/ellipse}
+```
+
+Output:
+
+{schema_inheritance:shapes/ellipse}
+
+### `json_file`
+
+Embed a JSON file into markdown, including syntax highlighting and reference links for JSON schema.
+
+Example:
+
+```
+{json_file:lottie.schema.json}
+```
+
+## Lottie Player
+
+### `<lottie>`
+
+Embeds a lottie into the document
+
+Example:
+
+```xml
+<lottie
+    src="static/logo.json"
+    width="200"
+    background="white"
+/>
+```
+
+Output:
+
+<lottie
+    src="static/logo.json"
+    width="200"
+    background="white"
+/>
+
+
+### `lottie-playground`
+
+Embeds a player side by side to a JSON snipped and controls to tweak the animation
+
+Example:
+
+```html
+<lottie-playground example="rectangle.json">
+    <title>Example</title>
+    <form>
+        <input title="Position x" type="range" min="0" max="512" value="256"/>
+        <input title="Position y" type="range" min="0" max="512" value="256"/>
+        <input title="Width" type="range" min="0" max="512" value="256"/>
+        <input title="Height" type="range" min="0" max="512" value="256"/>
+        <input title="Roundness" type="range" min="0" max="512" value="0"/>
+    </form>
+    <json>lottie.layers[0].shapes[0].it[0]</json>
+    <script>
+    lottie.layers[0].shapes[0].it[0].p.k = [
+        data["Position x"], data["Position y"]
+    ];
+    lottie.layers[0].shapes[0].it[0].s.k = [
+        data["Width"], data["Height"]
+    ];
+    lottie.layers[0].shapes[0].it[0].r.k = data["Roundness"];
+    </script>
+</lottie-playground>
+```
+
+Output:
+
+<lottie-playground example="rectangle.json">
+    <title>Example</title>
+    <form>
+        <input title="Position x" type="range" min="0" max="512" value="256"/>
+        <input title="Position y" type="range" min="0" max="512" value="256"/>
+        <input title="Width" type="range" min="0" max="512" value="256"/>
+        <input title="Height" type="range" min="0" max="512" value="256"/>
+        <input title="Roundness" type="range" min="0" max="512" value="0"/>
+    </form>
+    <json>lottie.layers[0].shapes[0].it[0]</json>
+    <script>
+    lottie.layers[0].shapes[0].it[0].p.k = [
+        data["Position x"], data["Position y"]
+    ];
+    lottie.layers[0].shapes[0].it[0].s.k = [
+        data["Width"], data["Height"]
+    ];
+    lottie.layers[0].shapes[0].it[0].r.k = data["Roundness"];
+    </script>
+</lottie-playground>

docs/editing/schema.md

@@ -0,0 +1,119 @@
+# Adding to the Schema
+
+The Lottie specification has a machine-readable definitions which uses
+[JSON Schema](https://json-schema.org/).
+
+There are many different ways of formatting the schema so here are some
+guidelines to ensure consistency.
+
+## Guidelines
+
+### Object Model Approach
+
+Objects in the schema are organized in a way that simulates an object model.
+
+This allows for implementation to have a (non-binding) foundation for their
+internal structure and provides easy organization of the human-readable
+documentation.
+
+This means there can be some "abstract" type definitions, which
+will contain the common properties and descriptions of concrete sub-types.
+
+Object inheritance is simulated using `allOf`, with `$ref` items referring to
+"base" definitions.
+
+### Split Files
+
+Each object or significant data type is split in its own file under `/schema`.
+These files are grouped together within a shallow list of directories.
+
+The files will be joined together into a single schema using `/tools/schema-merge.py`.
+
+### Required Properties
+
+Each type defined by the schema must have a `type`, as well as `title` and `description`.
+
+`title` should consist of a couple words that can be used to name the described object.
+
+`description` should contain a concise description that gives an idea of the purpose of that object.
+
+### Enumerations
+
+Enumerations are defined in a file under `/schema/constants` have `oneOf`
+defining, `title`, `description`, and `const` for every possible value
+of the enumeration.
+
+### `all` Files
+
+Some types have several sub-types in the schema, and properties might want
+to accept a value to any of the concrete sub-types.
+
+To ensure references to these types are consistent, you can create an additional
+schema file with the list of acceptable values.
+
+For example if you have an abstract type in `item.json`, the file will be
+`all-items.json`, and contain `oneOf` with `$ref`s to the acceptable types.
+
+
+## Writing Documentation
+
+Every type defined in the documentation must be documented.
+
+Schema documentation files go under `/docs/specs`, and there must be a
+file for each directory under `/schema`, with anchors for every type
+defined in that schema directory.
+
+### Pulling Data from the Schema
+
+There are several [Markdown extensions](extensions.md) available,
+every object and enumeration must have the relevant table to show its
+structure and an example playground should be provided for every visual element.
+
+
+### Building the Documentation
+
+There are several Python scripts that are used in the build process,
+ensure the requirements listed under `/tools/requirements.txt` are
+installed in your Python environment.
+
+The first step is to build the combined schema:
+
+```bash
+tools/schema-merge.py
+```
+
+It's important to call this after every schema change as the markdown
+extensions pull the data from this, and internal links are updated based
+on the combined file.
+
+To run the documentation locally you can use:
+
+```bash
+tools/mkdocs serve
+```
+
+This will create a local server that renders the documentation and it
+will reload if anything under `/docs` changes.
+
+To build a static HTML site run the following:
+
+```bash
+./tools/mkdocs build -d site
+```
+
+The output will be in `/site`.
+
+### Schema Validation
+
+You can validate schema syntax and internal references using
+
+```bash
+./tools/schema-validate.py
+```
+
+To validate that each section is documented, you can pass the path
+to the built site:
+
+```bash
+./tools/schema-validate.py --html site/specs/
+```

docs/governance/0._CS_Contributor_License_Agreement.md

@@ -0,0 +1 @@
+../../0._CS_Contributor_License_Agreement.md

docs/governance/1._Community_Specification_License-v1.md

@@ -0,0 +1 @@
+../../1._Community_Specification_License-v1.md

docs/governance/2._Scope.md

@@ -0,0 +1 @@
+../../2._Scope.md

docs/governance/3._Notices.md

@@ -0,0 +1 @@
+../../3._Notices.md

docs/governance/4._License.md

@@ -0,0 +1 @@
+../../4._License.md

docs/governance/5._Governance.md

@@ -0,0 +1 @@
+../../5._Governance.md

docs/governance/6._Contributing.md

@@ -0,0 +1 @@
+../../6._Contributing.md