feat(docs): Add documentation/gh-pages using Catalyst-CI docs builder…

…s and actions. (#104)

* refactor(gateway): Rename catalyst-voices-backend to the catalyst-gateway

* docs(gateway): Update readme

* refactor(gateway): Move the code into the new directory trees, cleanup inside tree still todo.

* refactor(gateway): Basic refactor of the event-db config/data and the db interface logic

* docs(gateway): Initial docs for the crates directory inside catalyst gateway

* refactor(gateway): Move code out of cat-data-service and put it directly in bin

* feat(gateway): first build seems to work, but fails due to WIP refactor

* refactor(gateway): Refactor builds properly to a static executable.

* refactor(gateway): autofixed lints

* refactor(gateway): WIP remove lint errors

* refactor(gateway): WIP refactoring work to remove lint errors

* refactor(gateway): Don't panic, return the error, and generalize the error itself.

* refactor(gateway): generalize error response

* docs(gateway): indexing ok here, slice already checked to have values

* refactor(gateway): Indexing is safe here, so note it.

* refactor(gateway): don't panic, return an error.  reduce size of function by splitting into multiple logical units.

* refactor(gateway): Purge metrics from legacy service.  Unused and can panic.

* refactor(gateway): remove unused rust files from EventDB directory

* refactor(gateway): remove unused dependencies

* docs(gateway): Allow intentional panic for test code

* refactor(gateway): eliminate or notate why unwraps/expect are safe

* refactor(gateway): All lints are clean and restrictively applied

* refactor(gateway): remove unused dependencies from workspace cargo file

* refactor(gateway): restrict visibility of event_db to pub(crate) as its fully internalized now.

* docs(gateway): root level fully documented

* docs(gateway): state fully documented

* docs(gateway): Don't worry about full docs for legacy service.

* docs(gateway): Service top level fully documented

* docs(gateway): middleware docs complete

* docs(gateway): Fully documented the docs part of the service

* docs(gateway): common responses and module root fully documented

* docs(gateway): Common objects now fully documented

* docs(gateway): Api endpoint docs are complete

* docs(gateway): DB Types fully documented

* docs(gateway): Queries partially documented

* docs(gateway): Everything that needs docs is documented

* feat(gateway): Initial CI and Cat-Gateway build ready for PR

* feat(rust): Add recommended rust extensions for vscode, and rust settings.

* docs(gateway): Fix spelling

* ci(gateway): Use the proper versioned CI tooling from catalyst-ci

* feat(docs): Docs WIP setup

* docs(docs): Fix the docs so they use the latests docs-ci and are able to properly include data from build targets

* docs(docs): fix spelling and markdown lint issues

* docs(docs): Update to use latest Cat-CI Docs and reduce replication

* docs(docs): Fix the top level parts of the docs and remove test values

* docs(docs): try and build and deploy docs to gh-pages

* docs(docs): fix spelling issue

* docs(docs): Use proper docs action, and also add branch cleanup for branch docs

* docs(docs): Use the published versions from Catalyst-CI

* docs(docs): Ensure we do not try and clean docs while building them.

* docs(docs): Ensure we don't try and build docs simultaneously, Don't build docs for tags.

* ci(mdlint): Use tagged CI versions for stability

* ci(spelling): Use tagged CI versions for stability

.config/dictionaries/project.dic

@@ -1,6 +1,7 @@
 aarch
 addrr
 adminer
+asyncio
 auditability
 BROTLI
 cardano
@@ -26,6 +27,8 @@ Intellij
 jetbrains
 jorm
 jormungandr
+Jörmungandr
+kroki
 lcov
 Leshiy
 localizable

.github/workflows/branch-delete-cleanup.yml

@@ -0,0 +1,13 @@
+name: Branch Deleted
+
+on: delete
+
+concurrency:
+  group: "docs"
+  cancel-in-progress: false
+
+jobs:
+  delete:
+    name: On branch deleted
+    if: github.event.ref_type == 'branch'
+    uses: input-output-hk/catalyst-ci/.github/workflows/[email protected]

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Docs
+
+# cspell: words earthfile
+
+on:
+  push:
+    tags-ignore:
+      - "*"
+
+concurrency:
+  group: "docs"
+  cancel-in-progress: false
+
+permissions:
+  id-token: write
+  contents: write
+  packages: write
+
+jobs:
+  ci:
+    uses: input-output-hk/catalyst-ci/.github/workflows/[email protected]
+    with:
+      aws_role_arn: arn:aws:iam::332405224602:role/ci
+      aws_region: eu-central-1
+      ci_cli_version: 1.3.1
+      earthfile: ./docs
+      target: docs
+    secrets:
+      earthly_runner_address: ${{ secrets.EARTHLY_SATELLITE_ADDRESS }}
+      earthly_runner_secret: ${{ secrets.EARTHLY_RUNNER_SECRET }}

.github/workflows/markdown-check.yml

@@ -11,4 +11,4 @@ on:
 jobs:
   build:
     name: Check markdown files formatted consistently
-    uses: input-output-hk/catalyst-ci/.github/workflows/markdown-check.yml@master
+    uses: input-output-hk/catalyst-ci/.github/workflows/markdown-check.yml@v2.0.6

.github/workflows/spell-check.yml

@@ -11,4 +11,4 @@ on:
 jobs:
   build:
     name: Check spelling across all files
-    uses: input-output-hk/catalyst-ci/.github/workflows/spell-check.yml@master
+    uses: input-output-hk/catalyst-ci/.github/workflows/spell-check.yml@v2.0.6

.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,
@@ -55,6 +56,22 @@
     "-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"
+  },
   "rust-analyzer.rustfmt.extraArgs": [
     "+nightly"
   ],

Earthfile

@@ -22,4 +22,12 @@ spell-check:
     LOCALLY
 
     DO github.com/input-output-hk/catalyst-ci/earthly/cspell:v1.3.0+CSPELL_LOCALLY --src=$(echo ${PWD})
-
+
+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

docs/Earthfile

@@ -0,0 +1,29 @@
+# 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:
+    # Common src setup
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.5+SRC
+
+    # 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:v2.0.5+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:v2.0.5+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/mkdocs.yml

@@ -0,0 +1,41 @@
+INHERIT: std-theme.yml
+
+# cspell: words cips
+
+# Project Information
+site_name: Project Catalyst - Catalyst Voices
+site_url: https://input-output-hk.github.io/catalyst-docs
+
+# Repository
+repo_name: input-output-hk/catalyst-voices
+repo_url: https://github.com/input-output-hk/catalyst-voices
+
+# Page tree
+nav:
+  - 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:
+      - Appendix: appendix/index.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/src/appendix/important/coc.md

@@ -0,0 +1,7 @@
+---
+icon: material/file-sign
+---
+
+<!-- markdownlint-disable first-line-h1 -->
+<!-- markdownlint-disable required-headers -->
+{{ include_file('includes/repo/CODE_OF_CONDUCT.md') }}

docs/src/appendix/important/contributing.md

@@ -0,0 +1,7 @@
+---
+icon: material/pen-plus
+---
+
+<!-- markdownlint-disable first-line-h1 -->
+<!-- markdownlint-disable required-headers -->
+{{ include_file('includes/repo/CONTRIBUTING.md') }}

docs/src/appendix/important/index.md

@@ -0,0 +1,5 @@
+---
+icon: material/alert-decagram-outline
+---
+
+# Important

docs/src/appendix/important/license.md

@@ -0,0 +1,19 @@
+---
+icon: material/license
+---
+
+# License
+
+<!-- markdownlint-disable max-one-sentence-per-line -->
+
+??? note "Apache 2 License"
+
+    ```text
+    {{ include_file('includes/repo/LICENSE-APACHE', 0, -1, 8) }}
+    ```
+
+??? note "MIT License"
+
+    ```text
+    {{ include_file('includes/repo/LICENSE-MIT', 0, -1, 8) }}
+    ```

docs/src/appendix/important/security.md

@@ -0,0 +1,7 @@
+---
+icon: material/security
+---
+
+<!-- markdownlint-disable first-line-h1 -->
+<!-- markdownlint-disable required-headers -->
+{{ include_file('includes/repo/SECURITY.md') }}

docs/src/appendix/index.md

@@ -0,0 +1,7 @@
+---
+icon: material/file-document-plus-outline
+---
+
+# Appendix
+
+The appendix contains collections of extra information and examples relevant to Catalyst Voices.

docs/src/catalyst-standards/ballot/catalyst-v1.md

@@ -0,0 +1,6 @@
+---
+icon: material/ballot
+---
+
+<!-- markdownlint-disable MD025-->
+# Catalyst Ballot Format V1

docs/src/catalyst-standards/ballot/catalyst-v2.md

@@ -0,0 +1,6 @@
+---
+icon: material/ballot-outline
+---
+
+<!-- markdownlint-disable MD025-->
+# Catalyst Ballot Format V2

docs/src/catalyst-standards/ballot/index.md

@@ -0,0 +1,6 @@
+---
+icon: material/ballot-recount-outline
+---
+
+<!-- markdownlint-disable MD025-->
+# Catalyst Ballot Formats

docs/src/catalyst-standards/draft-cips/.meta.yml

@@ -0,0 +1,2 @@
+status: new
+template: cip.html

docs/src/catalyst-standards/draft-cips/catalyst-vote-signing-cip30-extension/.meta.yml

@@ -0,0 +1 @@
+icon: material/vote-outline

docs/src/catalyst-standards/draft-cips/catalyst-vote-signing-cip30-extension/cip-xxxx.md

@@ -0,0 +1,69 @@
+---
+CIP: /?
+Title: Role based Access Control Registration
+Category: MetaData
+Status: Proposed
+Authors:
+    - Steven Johnson<[email protected]>
+Implementors: []
+Discussions:
+    - https://github.com/cardano-foundation/cips/pulls/?
+Created: 2023-10-24
+License: CC-BY-4.0
+--- 
+
+<!-- Existing categories:
+
+- Meta     | For meta-CIPs which typically serves another category or group of categories.
+- Wallets  | For standardization across wallets (hardware, full-node or light).
+- Tokens   | About tokens (fungible or non-fungible) and minting policies in general.
+- Metadata | For proposals around metadata (on-chain or off-chain).
+- Tools    | A broad category for ecosystem tools not falling into any other category.
+- Plutus   | Changes or additions to Plutus
+- Ledger   | For proposals regarding the Cardano ledger (including Reward Sharing Schemes)
+- Catalyst | For proposals affecting Project Catalyst / the Jormungandr project
+
+-->
+
+<!-- markdownlint-disable MD025-->
+# Role Based Access Control Registration
+
+## Abstract
+<!-- A short (\~200 word) description of the proposed solution and the technical issue being addressed. -->
+
+## Motivation: why is this CIP necessary?
+<!-- A clear explanation that introduces the reason for a proposal, its use cases and stakeholders. 
+If the CIP changes an established design then it must outline design issues that motivate a rework. 
+For complex proposals, authors must write a Cardano Problem Statement (CPS) as defined in CIP-9999 
+and link to it as the `Motivation`. -->
+
+## Specification
+<!-- The technical specification should describe the proposed improvement in sufficient technical detail. 
+In particular, it should provide enough information that an implementation can be performed solely on the basis 
+of the design in the CIP. 
+This is necessary to facilitate multiple, interoperable implementations. 
+This must include how the CIP should be versioned. 
+If a proposal defines structure of on-chain data it must include a CDDL schema in it's specification.-->
+
+## Rationale: how does this CIP achieve its goals?
+<!-- The rationale fleshes out the specification by describing what motivated the design and what led to 
+particular design decisions.
+It should describe alternate designs considered and related work. 
+The rationale should provide evidence of consensus within the community and discuss significant objections 
+or concerns raised during the discussion.
+
+It must also explain how the proposal affects the backward compatibility of existing solutions when applicable. 
+If the proposal responds to a CPS, the 'Rationale' section should explain how it addresses the CPS, 
+and answer any questions that the CPS poses for potential solutions.
+-->
+
+## Path to Active
+
+### Acceptance Criteria
+<!-- Describes what are the acceptance criteria whereby a proposal becomes 'Active' -->
+
+### Implementation Plan
+<!-- A plan to meet those criteria. Or `N/A` if not applicable. -->
+
+## Copyright
+<!-- The CIP must be explicitly licensed under acceptable copyright terms. -->

docs/src/catalyst-standards/draft-cips/index.md

@@ -0,0 +1,6 @@
+---
+icon: material/pencil-box-multiple-outline
+---
+
+<!-- markdownlint-disable MD025-->
+# Draft CIPs

docs/src/catalyst-standards/draft-cips/rbac-cip30-extension/.meta.yml

@@ -0,0 +1 @@
+icon: material/account-check