feat(docs): Add documentation/gh-pages using Catalyst-CI docs builders and actions.

.config/dictionaries/project.dic

@@ -1,5 +1,6 @@
 addrr
 adminer
+asyncio
 auditability
 BROTLI
 cardano
@@ -24,6 +25,8 @@ Intellij
 jetbrains
 jorm
 jormungandr
+Jörmungandr
+kroki
 lcov
 Leshiy
 localizable

.gitignore

@@ -78,3 +78,9 @@ $RECYCLE.BIN/
 !/.vscode/launch.recommended.json
 !/.vscode/settings.recommended.json
 !/.vscode/tasks.recommended.json
+
+# Local only development artefacts can get installed here.
+/local
+
+# We only want the actual document source from this directory.
+/docs/site/

.vscode/settings.recommended.json

@@ -4,7 +4,8 @@
   "editor.codeActionsOnSave": {
     "source.organizeImports": true,
     "source.sortMembers": true,
-    "source.fixAll": true
+    "source.fixAll": true,
+    "source.fixAll.markdownlint": true
   },
   "files.autoSave": "afterDelay",
   "editor.formatOnType": true,
@@ -54,5 +55,21 @@
     "bash",
     "-c",
     "cargo lint-vscode"
-  ]
+  ],
+  "yaml.schemas": {
+    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+  },
+  "yaml.customTags": [
+    "!ENV scalar",
+    "!ENV sequence",
+    "tag:yaml.org,2002:python/name:materialx.emoji.to_svg",
+    "tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
+    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+  ],
+  "[markdown]": {
+    "editor.formatOnSave": true,
+    "editor.formatOnPaste": true,
+    "files.trimTrailingWhitespace": true,
+    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
+  }
 }

Earthfile

@@ -29,3 +29,13 @@ global-cargo-config:
     FROM scratch
     COPY --dir .cargo .cargo
     SAVE ARTIFACT .cargo .cargo
+
+
+repo-docs:
+    # Create artifacts of extra files we embed inside the documentation when its built.
+    FROM scratch
+
+    WORKDIR /repo
+    COPY --dir *.md LICENSE-APACHE LICENSE-MIT .
+
+    SAVE ARTIFACT /repo repo

catalyst-gateway/Earthfile

@@ -15,9 +15,9 @@ COPY_SRC:
 
 builder:
     # The builder with all necessary tools and the correct rust versions.
-    FROM github.com/input-output-hk/catalyst-ci/earthly/rust:t1+rustup
+    FROM github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.1+rustup
 
-    DO github.com/input-output-hk/catalyst-ci/earthly/rust:t1+RUST_SETUP
+    DO github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.1+RUST_SETUP
 
     WORKDIR /build
 

docs/Earthfile

@@ -0,0 +1,31 @@
+# Set the Earthly version to 0.7
+VERSION 0.7
+
+# cspell: words mkdocs runable
+
+# Copy all the source we need to build the docs
+src:
+    FROM github.com/input-output-hk/catalyst-ci/earthly/docs:feat/docs3+mkdocs-material
+
+    # Just copy the actual doc src here.
+    COPY --dir src includes macros overrides mkdocs.yml /docs
+
+    # Now copy into that any artifacts we pull from the builds.
+    COPY --dir ../+repo-docs/repo /docs/includes
+
+# Build the docs here.
+docs:
+    FROM +src
+
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:feat/docs3+BUILD
+
+# Make a locally runable container that can serve the docs.
+local:
+    # Build a self contained service to show built docs locally.
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:feat/docs3+PACKAGE
+
+    # Copy the static pages into the container
+    COPY +docs/ /usr/share/nginx/html
+
+    # This is a local only image, we do not publish it.
+    SAVE IMAGE cat-voices-docs:latest

docs/includes/abbreviations.md

@@ -0,0 +1,3 @@
+<!-- markdownlint-disable MD041 MD043-->
+*[HTML]: Hyper Text Markup Language
+*[W3C]: World Wide Web Consortium

docs/includes/repo/CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+# File replaced during documentation build

docs/includes/repo/CONTRIBUTING.md

@@ -0,0 +1 @@
+# File replaced during documentation build

docs/includes/repo/LICENSE-APACHE

@@ -0,0 +1 @@
+# File replaced during documentation build

docs/includes/repo/LICENSE-MIT

@@ -0,0 +1 @@
+# File replaced during documentation build

docs/includes/repo/README.md

@@ -0,0 +1,10 @@
+# Repo Documents
+
+These files are replaced during the build with documentation files maintained
+globally to the repo.
+
+Such documents are importantly used not just inside the documentation, but also
+for people browsing the source repository.
+
+All files in this directory are just placeholders, until the documentation build
+replaces them with the appropriate files.

docs/includes/repo/SECURITY.md

@@ -0,0 +1 @@
+# File replaced during documentation build

docs/macros/__init__.py

@@ -0,0 +1,11 @@
+from .include import inc_file
+
+
+def define_env(env):
+    """
+    This is the hook for defining variables, macros and filters
+    """
+
+    @env.macro
+    def include_file(filename, start_line=0, end_line=None, indent=None):
+        return inc_file(env, filename, start_line, end_line, indent)

docs/macros/include.py

@@ -0,0 +1,25 @@
+import os
+import textwrap
+
+def inc_file(env, filename, start_line=0, end_line=None, indent=None):
+    """
+    Include a file, optionally indicating start_line and end_line
+    (start counting from 0)
+    The path is relative to the top directory of the documentation
+    project.
+    """
+
+    try:
+        full_filename = os.path.join(env.project_dir, filename)
+
+        with open(full_filename, "r") as f:
+            lines = f.readlines()
+        line_range = lines[start_line:end_line]
+        text = "".join(line_range)
+        if indent is None:
+            indent = ""
+        else:
+            indent = " " * indent
+        return textwrap.indent(text, indent)
+    except Exception as exc:
+        return f"{filename} error: {exc}"

docs/mkdocs.yml

@@ -0,0 +1,152 @@
+# Project Information
+site_name: Project Catalyst - Catalyst Voices
+site_url: https://input-output-hk.github.io/catalyst-docs
+site_author: The Project Catalyst Team
+copyright: (c) 2023 Input Output Global
+
+# cspell: words Diagramsnet, pymdownx, linenums, inlinehilite, superfences,
+# cspell: words tasklist, betterem, materialx, twemoji, smartsymbols,
+# cspell: words kroki, excalidraw, glightbox, cips, pygments, arithmatex
+
+# Repository
+repo_name: input-output-hk/catalyst-voices
+repo_url: https://github.com/input-output-hk/catalyst-voices
+
+# The Documentation src to build.
+docs_dir: src
+
+theme:
+  name: material
+  custom_dir: overrides
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      media: "(prefers-color-scheme: light)"
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      media: "(prefers-color-scheme: dark)"
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  features:
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.tracking
+    #- navigation.tabs
+    #- navigation.tabs.sticky
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.indexes
+    - toc.follow
+    - toc.integrate
+    - search.suggest
+    - search.highlight
+
+plugins:
+  - search
+  - meta-manager
+  - macros:
+      module_name: macros
+  # - diagrams - Plugin is installed, but produces corrupted output
+  - kroki:
+      ServerURL: https://kroki.io
+      EnableDiagramsnet: true
+      HttpMethod: POST
+  - glightbox
+
+markdown_extensions:
+  # Python Markdown
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+
+  # Python Markdown Extensions
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      auto_append:
+        - includes/abbreviations.md
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra:
+  consent:
+    title: Cookie consent
+    description: >-
+
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.
+
+# Page tree
+nav:
+  - Home:
+      - Home: index.md
+      - Getting Started:
+          - Getting Started: getting-started/index.md
+          - Quick Start: getting-started/quick-start.md
+          - Advanced: getting-started/advanced.md
+          - Development: getting-started/development.md
+      - Monorepo Architecture:
+          - Monorepo Architecture: monorepo-architecture/index.md
+      - Catalyst Standards:
+          - Catalyst Standards: catalyst-standards/index.md
+          - Draft CIPs:
+              - Draft CIPs: catalyst-standards/draft-cips/index.md
+              - Role Registration: catalyst-standards/draft-cips/role-registration/cip-xxxx.md
+              - RBAC CIP30 Extension: catalyst-standards/draft-cips/rbac-cip30-extension/cip-xxxx.md
+              - Catalyst Voting CIP30 Extension: catalyst-standards/draft-cips/catalyst-vote-signing-cip30-extension/cip-xxxx.md
+          - Catalyst Ballot Formats:
+              - Catalyst Ballot Formats: catalyst-standards/ballot/index.md
+              - Catalyst V1 Ballot: catalyst-standards/ballot/catalyst-v1.md
+              - Catalyst V2 Ballot: catalyst-standards/ballot/catalyst-v2.md
+      - Appendix:
+          - Documentation Examples:
+              - Examples: appendix/examples/index.md
+              - Abbreviations: appendix/examples/abbreviations.md
+              - Admonitions: appendix/examples/admonitions.md
+              - Code Formatting: appendix/examples/code-formatting.md
+              - Mermaid Diagrams: appendix/examples/mermaid-diagrams.md
+              - Kroki Diagrams: appendix/examples/kroki-diagrams.md
+          - Important Information:
+              - Important Information: appendix/important/index.md
+              - Contributing: appendix/important/contributing.md
+              - Code of Conduct: appendix/important/coc.md
+              - Security: appendix/important/security.md
+              - License: appendix/important/license.md

docs/overrides/cip.html

@@ -0,0 +1,43 @@
+{% extends "base.html" %}
+
+<!-- Page content -->
+{% block container %}
+<div class="md-content" data-md-component="content">
+    <article class="md-content__inner md-typeset">
+        {% if page.meta %}
+            {% if page.meta.CIP %} 
+                CIP: {{ page.meta.CIP }} <br/> 
+                {% if page.meta.Title %} 
+                    Title: {{ page.meta.Title }} <br/> 
+                {% endif %}
+                {% if page.meta.Category %} 
+                    Category: {{ page.meta.Category }} <br/> 
+                {% endif %}
+                {% if page.meta.Status %} 
+                    Status: {{ page.meta.Status }} <br/> 
+                {% endif %}
+                {% if page.meta.Authors %} 
+                    Authors: {{ page.meta.Authors }} <br/> 
+                {% endif %}
+                {% if page.meta.Implementors %} 
+                    Status: {{ page.meta.Implementors }} <br/> 
+                {% endif %}
+                {% if page.meta.Discussions %} 
+                    Status: {{ page.meta.Discussions }} <br/> 
+                {% endif %}
+                {% if page.meta.Created %} 
+                    Status: {{ page.meta.Created }} <br/> 
+                {% endif %}
+                {% if page.meta.License %} 
+                    Status: {{ page.meta.License }} <br/> 
+                {% endif %}
+                <br/>
+            {% endif %}
+        {% endif %}
+
+        {% block content %}
+        {% include "partials/content.html" %}
+        {% endblock %}
+    </article>
+</div>
+{% endblock %}

docs/src/appendix/examples/abbreviations.md

@@ -0,0 +1,13 @@
+---
+icon: material/text-short
+---
+
+# Consistent Abbreviations
+
+The HTML Specification is maintained by the W3C.
+
+<!-- markdownlint-disable max-one-sentence-per-line -->
+
+!!! note
+
+    Abbreviations go in the `docs/includes/abbreviations.md` file.