docs(docs): Update to latest docs builder, add architecture docs temp…

…lates (#153)

Force merged due to long delay sitting in review, and it's blocking me from doing DB design docs.

.config/dictionaries/project.dic

@@ -28,6 +28,7 @@ dotglob
 drep
 dreps
 encryptor
+fontawesome
 gapless
 gcloud
 genhtml
@@ -90,4 +91,4 @@ xcodeproj
 xctest
 xctestrun
 xcworkspace
-yoroi
+yoroi

.vscode/settings.recommended.json

@@ -66,6 +66,17 @@
     "tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
     "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
   ],
+  "[yaml]": {
+    "editor.insertSpaces": true,
+    "editor.tabSize": 2,
+    "editor.autoIndent": "advanced",
+    "diffEditor.ignoreTrimWhitespace": false,
+    "editor.quickSuggestions": {
+      "other": true,
+      "comments": false,
+      "strings": true
+    }
+  },
   "[markdown]": {
     "editor.formatOnSave": true,
     "editor.formatOnPaste": true,

docs/Earthfile

@@ -6,7 +6,7 @@ VERSION 0.7
 # 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
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.8+SRC
 
     # Now copy into that any artifacts we pull from the builds.
     COPY --dir ../+repo-docs/repo /docs/includes
@@ -15,12 +15,12 @@ src:
 docs:
     FROM +src
 
-    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.5+BUILD
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.8+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
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.8+PACKAGE
 
     # Copy the static pages into the container
     COPY +docs/ /usr/share/nginx/html

docs/mkdocs.yml

@@ -10,32 +10,38 @@ site_url: https://input-output-hk.github.io/catalyst-docs
 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
+# Page tree - is created automatically.
+# See: https://henrywhitaker3.github.io/mkdocs-material-dark-theme/plugins/awesome-pages/
+
+# Tags used in these docs
+extra:
+  tags:
+    HTML5: html
+    JavaScript: js
+    CSS: css
+    Rust: rust
+    Flutter: flutter
+    Dart: dart
+    Python: python
+    Earthly: earthly
+    Github: github
+    Docker: docker
+    arc42: arc42
+    ADR: adr
+
+# Icons associated with the tags
+theme:
+  icon:
+    tag:
+      html: fontawesome/brands/html5
+      js: fontawesome/brands/js
+      css: fontawesome/brands/css3
+      rust: simple/rust
+      flutter: simple/flutter
+      dart: simple/dart
+      python: simple/python
+      earthly: material/earth-plus
+      github: simple/github
+      docker: simple/docker
+      arc42: material/pencil-ruler
+      adr: material/arrow-decision-auto

docs/src/.pages

@@ -0,0 +1,6 @@
+arrange:
+  - index.md
+  - getting-started
+  - catalyst-standards
+  - architecture
+  - appendix

docs/src/appendix/important/.pages

@@ -0,0 +1,6 @@
+arrange:
+  - index.md
+  - contributing.md
+  - coc.md
+  - security.md
+  - license.md

docs/src/appendix/important/coc.md

@@ -1,5 +1,6 @@
 ---
 icon: material/file-sign
+title: Code of Conduct
 ---
 
 <!-- markdownlint-disable first-line-h1 -->

docs/src/appendix/tags.md

@@ -0,0 +1,7 @@
+---
+icon: fontawesome/solid/tags
+---
+
+# Tag Index
+
+[TAGS]

docs/src/architecture/.pages

@@ -0,0 +1,14 @@
+arrange:
+  - index.md
+  - 01_introduction_and_goals.md
+  - 02_architecture_constraints.md
+  - 03_system_scope_and_context.md
+  - 04_solution_strategy.md
+  - 05_building_block_view.md
+  - 06_runtime_view.md
+  - 07_deployment_view.md
+  - 08_concepts.md
+  - 09_architecture_decisions
+  - 10_quality_requirements.md
+  - 11_technical_risks.md
+  - 12_glossary.md

docs/src/architecture/01_introduction_and_goals.md

@@ -0,0 +1,18 @@
+---
+icon: octicons/goal-24
+---
+
+# Introduction and Goals
+
+<!-- See: https://docs.arc42.org/section-1/ -->
+
+## Requirements Overview
+
+## Quality Goals
+
+## Stakeholders
+
+| Role/Name   | Contact        | Expectations       |
+|-------------|----------------|--------------------|
+| *~Role-1~* | *~Contact-1~* | *~Expectation-1~* |
+| *~Role-2~* | *~Contact-2~* | *~Expectation-2~* |

docs/src/architecture/02_architecture_constraints.md

@@ -0,0 +1,7 @@
+---
+icon: material/handcuffs
+---
+
+# Architecture Constraints
+
+<!-- See: https://docs.arc42.org/section-2/ -->

docs/src/architecture/03_system_scope_and_context.md

@@ -0,0 +1,21 @@
+---
+icon: material/telescope
+---
+
+# System Scope and Context
+
+<!-- See: https://docs.arc42.org/section-3/ -->
+
+## Business Context
+
+... **~Diagram or Table~**
+
+... **~optionally: Explanation of external domain interfaces~**
+
+## Technical Context
+
+... **~Diagram or Table~**
+
+... **~optionally: Explanation of technical interfaces~**
+
+... **~Mapping Input/Output to Channels~**

docs/src/architecture/04_solution_strategy.md

@@ -0,0 +1,7 @@
+---
+icon: material/strategy
+---
+
+# Solution Strategy
+
+<!-- See: https://docs.arc42.org/section-4/ -->

docs/src/architecture/05_building_block_view.md

@@ -0,0 +1,78 @@
+---
+icon: material/toy-brick-search
+---
+
+# Building Block View
+
+<!-- See: https://docs.arc42.org/section-5/ -->
+
+## White box Overall System
+
+... ***~Overview Diagram~***
+
+Motivation  
+... *~text explanation~*
+
+Contained Building Blocks  
+... *~Description of contained building block (black boxes)~*
+
+Important Interfaces  
+... *~Description of important interfaces~*
+
+### ~Name black box 1~
+
+... *~Purpose/Responsibility~*
+
+... *~Interface(s)~*
+
+... *~(Optional) Quality/Performance Characteristics~*
+
+... *~(Optional) Directory/File Location~*
+
+... *~(Optional) Fulfilled Requirements~*
+
+... *~(optional) Open Issues/Problems/Risks~*
+
+### ~Name black box 2~
+
+... *~black box template~*
+
+### ~Name black box n~
+
+... *~black box template~*
+
+### ~Name interface 1~
+
+…
+
+### ~Name interface m~
+
+## Level 2
+
+### White Box *~building block 1~*
+
+... *~white box template~*
+
+### White Box *~building block 2~*
+
+... *~white box template~*
+
+…
+
+### White Box *~building block m~*
+
+... *~white box template~*
+
+## Level 3
+
+### White Box ~\_building block x.1\_\~
+
+... *~white box template~*
+
+### White Box ~\_building block x.2\_\~
+
+... *~white box template~*
+
+### White Box ~\_building block y.1\_\~
+
+... *~white box template~*

docs/src/architecture/06_runtime_view.md

@@ -0,0 +1,20 @@
+---
+icon: material/run-fast
+---
+
+# Runtime View
+
+<!-- See: https://docs.arc42.org/section-6/ -->
+
+## ~Runtime Scenario 1~
+
+* *~insert runtime diagram or textual description of the scenario~*
+
+* *~insert description of the notable aspects of the interactions
+    between the building block instances depicted in this diagram.~*
+
+## ~Runtime Scenario 2~
+
+## …
+
+## ~Runtime Scenario n~

docs/src/architecture/07_deployment_view.md

@@ -0,0 +1,36 @@
+---
+icon: material/server-network
+---
+
+# Deployment View
+
+<!-- See: https://docs.arc42.org/section-7/ -->
+
+## Infrastructure Level 1
+
+... ***~Overview Diagram~***
+
+Motivation  
+... *~explanation in text form~*
+
+Quality and/or Performance Features  
+... *~explanation in text form~*
+
+Mapping of Building Blocks to Infrastructure  
+... *~description of the mapping~*
+
+## Infrastructure Level 2
+
+### *~Infrastructure Element 1~*
+
+... *~diagram + explanation~*
+
+### *~Infrastructure Element 2~*
+
+... *~diagram + explanation~*
+
+…
+
+### *~Infrastructure Element n~*
+
+... *~diagram + explanation~*

docs/src/architecture/08_concepts.md

@@ -0,0 +1,21 @@
+---
+icon: material/thought-bubble
+---
+
+# Cross-cutting Concepts
+
+<!-- See: https://docs.arc42.org/section-8/ -->
+
+## *~Concept 1~*
+
+... *~explanation~*
+
+## *~Concept 2~*
+
+... *~explanation~*
+
+…
+
+## *~Concept n~*
+
+... *~explanation~*

docs/src/architecture/09_architecture_decisions/.pages

@@ -0,0 +1 @@
+title: Architecture Decisions