Skip to content

Commit 54bd4ec

Browse files
stevenjstevenj
authored
docs(docs): Update to latest docs builder, add architecture docs templates (#153)
Force merged due to long delay sitting in review, and it's blocking me from doing DB design docs.
1 parent a17bd81 commit 54bd4ec

34 files changed

+510
-76
lines changed

‎.config/dictionaries/project.dic

+2-1
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ dotglob
2828
drep
2929
dreps
3030
encryptor
31+
fontawesome
3132
gapless
3233
gcloud
3334
genhtml
@@ -90,4 +91,4 @@ xcodeproj
9091
xctest
9192
xctestrun
9293
xcworkspace
93-
yoroi
94+
yoroi

‎.vscode/settings.recommended.json

+11
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,17 @@
6666
"tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
6767
"tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
6868
],
69+
"[yaml]": {
70+
"editor.insertSpaces": true,
71+
"editor.tabSize": 2,
72+
"editor.autoIndent": "advanced",
73+
"diffEditor.ignoreTrimWhitespace": false,
74+
"editor.quickSuggestions": {
75+
"other": true,
76+
"comments": false,
77+
"strings": true
78+
}
79+
},
6980
"[markdown]": {
7081
"editor.formatOnSave": true,
7182
"editor.formatOnPaste": true,

‎docs/Earthfile

+3-3
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ VERSION 0.7
66
# Copy all the source we need to build the docs
77
src:
88
# Common src setup
9-
DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.5+SRC
9+
DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.8+SRC
1010

1111
# Now copy into that any artifacts we pull from the builds.
1212
COPY --dir ../+repo-docs/repo /docs/includes
@@ -15,12 +15,12 @@ src:
1515
docs:
1616
FROM +src
1717

18-
DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.5+BUILD
18+
DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.8+BUILD
1919

2020
# Make a locally runable container that can serve the docs.
2121
local:
2222
# Build a self contained service to show built docs locally.
23-
DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.5+PACKAGE
23+
DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.8+PACKAGE
2424

2525
# Copy the static pages into the container
2626
COPY +docs/ /usr/share/nginx/html

‎docs/mkdocs.yml

+35-29
Original file line numberDiff line numberDiff line change
@@ -10,32 +10,38 @@ site_url: https://input-output-hk.github.io/catalyst-docs
1010
repo_name: input-output-hk/catalyst-voices
1111
repo_url: https://github.com/input-output-hk/catalyst-voices
1212

13-
# Page tree
14-
nav:
15-
- Home: index.md
16-
- Getting Started:
17-
- Getting Started: getting-started/index.md
18-
- Quick Start: getting-started/quick-start.md
19-
- Advanced: getting-started/advanced.md
20-
- Development: getting-started/development.md
21-
- Monorepo Architecture:
22-
- Monorepo Architecture: monorepo-architecture/index.md
23-
- Catalyst Standards:
24-
- Catalyst Standards: catalyst-standards/index.md
25-
- Draft CIPs:
26-
- Draft CIPs: catalyst-standards/draft-cips/index.md
27-
- Role Registration: catalyst-standards/draft-cips/role-registration/cip-xxxx.md
28-
- RBAC CIP30 Extension: catalyst-standards/draft-cips/rbac-cip30-extension/cip-xxxx.md
29-
- Catalyst Voting CIP30 Extension: catalyst-standards/draft-cips/catalyst-vote-signing-cip30-extension/cip-xxxx.md
30-
- Catalyst Ballot Formats:
31-
- Catalyst Ballot Formats: catalyst-standards/ballot/index.md
32-
- Catalyst V1 Ballot: catalyst-standards/ballot/catalyst-v1.md
33-
- Catalyst V2 Ballot: catalyst-standards/ballot/catalyst-v2.md
34-
- Appendix:
35-
- Appendix: appendix/index.md
36-
- Important Information:
37-
- Important Information: appendix/important/index.md
38-
- Contributing: appendix/important/contributing.md
39-
- Code of Conduct: appendix/important/coc.md
40-
- Security: appendix/important/security.md
41-
- License: appendix/important/license.md
13+
# Page tree - is created automatically.
14+
# See: https://henrywhitaker3.github.io/mkdocs-material-dark-theme/plugins/awesome-pages/
15+
16+
# Tags used in these docs
17+
extra:
18+
tags:
19+
HTML5: html
20+
JavaScript: js
21+
CSS: css
22+
Rust: rust
23+
Flutter: flutter
24+
Dart: dart
25+
Python: python
26+
Earthly: earthly
27+
Github: github
28+
Docker: docker
29+
arc42: arc42
30+
ADR: adr
31+
32+
# Icons associated with the tags
33+
theme:
34+
icon:
35+
tag:
36+
html: fontawesome/brands/html5
37+
js: fontawesome/brands/js
38+
css: fontawesome/brands/css3
39+
rust: simple/rust
40+
flutter: simple/flutter
41+
dart: simple/dart
42+
python: simple/python
43+
earthly: material/earth-plus
44+
github: simple/github
45+
docker: simple/docker
46+
arc42: material/pencil-ruler
47+
adr: material/arrow-decision-auto

‎docs/src/.pages

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
arrange:
2+
- index.md
3+
- getting-started
4+
- catalyst-standards
5+
- architecture
6+
- appendix

‎docs/src/appendix/important/.pages

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
arrange:
2+
- index.md
3+
- contributing.md
4+
- coc.md
5+
- security.md
6+
- license.md

‎docs/src/appendix/important/coc.md

+1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
icon: material/file-sign
3+
title: Code of Conduct
34
---
45

56
<!-- markdownlint-disable first-line-h1 -->

‎docs/src/appendix/tags.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
icon: fontawesome/solid/tags
3+
---
4+
5+
# Tag Index
6+
7+
[TAGS]

‎docs/src/architecture/.pages

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
arrange:
2+
- index.md
3+
- 01_introduction_and_goals.md
4+
- 02_architecture_constraints.md
5+
- 03_system_scope_and_context.md
6+
- 04_solution_strategy.md
7+
- 05_building_block_view.md
8+
- 06_runtime_view.md
9+
- 07_deployment_view.md
10+
- 08_concepts.md
11+
- 09_architecture_decisions
12+
- 10_quality_requirements.md
13+
- 11_technical_risks.md
14+
- 12_glossary.md

‎docs/src/architecture/01_introduction_and_goals.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
icon: octicons/goal-24
3+
---
4+
5+
# Introduction and Goals
6+
7+
<!-- See: https://docs.arc42.org/section-1/ -->
8+
9+
## Requirements Overview
10+
11+
## Quality Goals
12+
13+
## Stakeholders
14+
15+
| Role/Name | Contact | Expectations |
16+
|-------------|----------------|--------------------|
17+
| *~Role-1~* | *~Contact-1~* | *~Expectation-1~* |
18+
| *~Role-2~* | *~Contact-2~* | *~Expectation-2~* |

‎docs/src/architecture/02_architecture_constraints.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
icon: material/handcuffs
3+
---
4+
5+
# Architecture Constraints
6+
7+
<!-- See: https://docs.arc42.org/section-2/ -->

‎docs/src/architecture/03_system_scope_and_context.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
icon: material/telescope
3+
---
4+
5+
# System Scope and Context
6+
7+
<!-- See: https://docs.arc42.org/section-3/ -->
8+
9+
## Business Context
10+
11+
... **~Diagram or Table~**
12+
13+
... **~optionally: Explanation of external domain interfaces~**
14+
15+
## Technical Context
16+
17+
... **~Diagram or Table~**
18+
19+
... **~optionally: Explanation of technical interfaces~**
20+
21+
... **~Mapping Input/Output to Channels~**

‎docs/src/architecture/04_solution_strategy.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
icon: material/strategy
3+
---
4+
5+
# Solution Strategy
6+
7+
<!-- See: https://docs.arc42.org/section-4/ -->

‎docs/src/architecture/05_building_block_view.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
icon: material/toy-brick-search
3+
---
4+
5+
# Building Block View
6+
7+
<!-- See: https://docs.arc42.org/section-5/ -->
8+
9+
## White box Overall System
10+
11+
... ***~Overview Diagram~***
12+
13+
Motivation
14+
... *~text explanation~*
15+
16+
Contained Building Blocks
17+
... *~Description of contained building block (black boxes)~*
18+
19+
Important Interfaces
20+
... *~Description of important interfaces~*
21+
22+
### ~Name black box 1~
23+
24+
... *~Purpose/Responsibility~*
25+
26+
... *~Interface(s)~*
27+
28+
... *~(Optional) Quality/Performance Characteristics~*
29+
30+
... *~(Optional) Directory/File Location~*
31+
32+
... *~(Optional) Fulfilled Requirements~*
33+
34+
... *~(optional) Open Issues/Problems/Risks~*
35+
36+
### ~Name black box 2~
37+
38+
... *~black box template~*
39+
40+
### ~Name black box n~
41+
42+
... *~black box template~*
43+
44+
### ~Name interface 1~
45+
46+
…
47+
48+
### ~Name interface m~
49+
50+
## Level 2
51+
52+
### White Box *~building block 1~*
53+
54+
... *~white box template~*
55+
56+
### White Box *~building block 2~*
57+
58+
... *~white box template~*
59+
60+
…
61+
62+
### White Box *~building block m~*
63+
64+
... *~white box template~*
65+
66+
## Level 3
67+
68+
### White Box ~\_building block x.1\_\~
69+
70+
... *~white box template~*
71+
72+
### White Box ~\_building block x.2\_\~
73+
74+
... *~white box template~*
75+
76+
### White Box ~\_building block y.1\_\~
77+
78+
... *~white box template~*

‎docs/src/architecture/06_runtime_view.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
icon: material/run-fast
3+
---
4+
5+
# Runtime View
6+
7+
<!-- See: https://docs.arc42.org/section-6/ -->
8+
9+
## ~Runtime Scenario 1~
10+
11+
* *~insert runtime diagram or textual description of the scenario~*
12+
13+
* *~insert description of the notable aspects of the interactions
14+
between the building block instances depicted in this diagram.~*
15+
16+
## ~Runtime Scenario 2~
17+
18+
## …
19+
20+
## ~Runtime Scenario n~

‎docs/src/architecture/07_deployment_view.md

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
icon: material/server-network
3+
---
4+
5+
# Deployment View
6+
7+
<!-- See: https://docs.arc42.org/section-7/ -->
8+
9+
## Infrastructure Level 1
10+
11+
... ***~Overview Diagram~***
12+
13+
Motivation
14+
... *~explanation in text form~*
15+
16+
Quality and/or Performance Features
17+
... *~explanation in text form~*
18+
19+
Mapping of Building Blocks to Infrastructure
20+
... *~description of the mapping~*
21+
22+
## Infrastructure Level 2
23+
24+
### *~Infrastructure Element 1~*
25+
26+
... *~diagram + explanation~*
27+
28+
### *~Infrastructure Element 2~*
29+
30+
... *~diagram + explanation~*
31+
32+
…
33+
34+
### *~Infrastructure Element n~*
35+
36+
... *~diagram + explanation~*

‎docs/src/architecture/08_concepts.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
icon: material/thought-bubble
3+
---
4+
5+
# Cross-cutting Concepts
6+
7+
<!-- See: https://docs.arc42.org/section-8/ -->
8+
9+
## *~Concept 1~*
10+
11+
... *~explanation~*
12+
13+
## *~Concept 2~*
14+
15+
... *~explanation~*
16+
17+
…
18+
19+
## *~Concept n~*
20+
21+
... *~explanation~*

‎docs/src/architecture/09_architecture_decisions/.pages

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
title: Architecture Decisions

0 commit comments

Comments
 (0)