Skip to content

Commit 8262fbd

Browse files
stevenjstevenj
authored
feat(docs): Add documentation/gh-pages using Catalyst-CI docs builders 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
1 parent 3e2efa7 commit 8262fbd

39 files changed

+516
-4
lines changed

‎.config/dictionaries/project.dic

+3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
aarch
22
addrr
33
adminer
4+
asyncio
45
auditability
56
BROTLI
67
cardano
@@ -26,6 +27,8 @@ Intellij
2627
jetbrains
2728
jorm
2829
jormungandr
30+
Jörmungandr
31+
kroki
2932
lcov
3033
Leshiy
3134
localizable

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

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
name: Branch Deleted
2+
3+
on: delete
4+
5+
concurrency:
6+
group: "docs"
7+
cancel-in-progress: false
8+
9+
jobs:
10+
delete:
11+
name: On branch deleted
12+
if: github.event.ref_type == 'branch'
13+
uses: input-output-hk/catalyst-ci/.github/workflows/[email protected]

‎.github/workflows/docs.yml

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Docs
2+
3+
# cspell: words earthfile
4+
5+
on:
6+
push:
7+
tags-ignore:
8+
- "*"
9+
10+
concurrency:
11+
group: "docs"
12+
cancel-in-progress: false
13+
14+
permissions:
15+
id-token: write
16+
contents: write
17+
packages: write
18+
19+
jobs:
20+
ci:
21+
uses: input-output-hk/catalyst-ci/.github/workflows/[email protected]
22+
with:
23+
aws_role_arn: arn:aws:iam::332405224602:role/ci
24+
aws_region: eu-central-1
25+
ci_cli_version: 1.3.1
26+
earthfile: ./docs
27+
target: docs
28+
secrets:
29+
earthly_runner_address: ${{ secrets.EARTHLY_SATELLITE_ADDRESS }}
30+
earthly_runner_secret: ${{ secrets.EARTHLY_RUNNER_SECRET }}

‎.github/workflows/markdown-check.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ on:
1111
jobs:
1212
build:
1313
name: Check markdown files formatted consistently
14-
uses: input-output-hk/catalyst-ci/.github/workflows/markdown-check.yml@master
14+
uses: input-output-hk/catalyst-ci/.github/workflows/markdown-check.yml@v2.0.6

‎.github/workflows/spell-check.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ on:
1111
jobs:
1212
build:
1313
name: Check spelling across all files
14-
uses: input-output-hk/catalyst-ci/.github/workflows/spell-check.yml@master
14+
uses: input-output-hk/catalyst-ci/.github/workflows/spell-check.yml@v2.0.6

‎.gitignore

+6
Original file line numberDiff line numberDiff line change
@@ -78,3 +78,9 @@ $RECYCLE.BIN/
7878
!/.vscode/launch.recommended.json
7979
!/.vscode/settings.recommended.json
8080
!/.vscode/tasks.recommended.json
81+
82+
# Local only development artefacts can get installed here.
83+
/local
84+
85+
# We only want the actual document source from this directory.
86+
/docs/site/

‎.vscode/settings.recommended.json

+18-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44
"editor.codeActionsOnSave": {
55
"source.organizeImports": true,
66
"source.sortMembers": true,
7-
"source.fixAll": true
7+
"source.fixAll": true,
8+
"source.fixAll.markdownlint": true
89
},
910
"files.autoSave": "afterDelay",
1011
"editor.formatOnType": true,
@@ -55,6 +56,22 @@
5556
"-c",
5657
"cargo lint-vscode"
5758
],
59+
"yaml.schemas": {
60+
"https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
61+
},
62+
"yaml.customTags": [
63+
"!ENV scalar",
64+
"!ENV sequence",
65+
"tag:yaml.org,2002:python/name:materialx.emoji.to_svg",
66+
"tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
67+
"tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
68+
],
69+
"[markdown]": {
70+
"editor.formatOnSave": true,
71+
"editor.formatOnPaste": true,
72+
"files.trimTrailingWhitespace": true,
73+
"editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
74+
},
5875
"rust-analyzer.rustfmt.extraArgs": [
5976
"+nightly"
6077
],

‎Earthfile

+9-1
Original file line numberDiff line numberDiff line change
@@ -22,4 +22,12 @@ spell-check:
2222
LOCALLY
2323

2424
DO github.com/input-output-hk/catalyst-ci/earthly/cspell:v1.3.0+CSPELL_LOCALLY --src=$(echo ${PWD})
25-
25+
26+
repo-docs:
27+
# Create artifacts of extra files we embed inside the documentation when its built.
28+
FROM scratch
29+
30+
WORKDIR /repo
31+
COPY --dir *.md LICENSE-APACHE LICENSE-MIT .
32+
33+
SAVE ARTIFACT /repo repo

‎docs/Earthfile

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Set the Earthly version to 0.7
2+
VERSION 0.7
3+
4+
# cspell: words mkdocs runable
5+
6+
# Copy all the source we need to build the docs
7+
src:
8+
# Common src setup
9+
DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.5+SRC
10+
11+
# Now copy into that any artifacts we pull from the builds.
12+
COPY --dir ../+repo-docs/repo /docs/includes
13+
14+
# Build the docs here.
15+
docs:
16+
FROM +src
17+
18+
DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.5+BUILD
19+
20+
# Make a locally runable container that can serve the docs.
21+
local:
22+
# 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
24+
25+
# Copy the static pages into the container
26+
COPY +docs/ /usr/share/nginx/html
27+
28+
# This is a local only image, we do not publish it.
29+
SAVE IMAGE cat-voices-docs:latest

‎docs/mkdocs.yml

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
INHERIT: std-theme.yml
2+
3+
# cspell: words cips
4+
5+
# Project Information
6+
site_name: Project Catalyst - Catalyst Voices
7+
site_url: https://input-output-hk.github.io/catalyst-docs
8+
9+
# Repository
10+
repo_name: input-output-hk/catalyst-voices
11+
repo_url: https://github.com/input-output-hk/catalyst-voices
12+
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

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

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

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

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
icon: material/pen-plus
3+
---
4+
5+
<!-- markdownlint-disable first-line-h1 -->
6+
<!-- markdownlint-disable required-headers -->
7+
{{ include_file('includes/repo/CONTRIBUTING.md') }}

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

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
icon: material/alert-decagram-outline
3+
---
4+
5+
# Important

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

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
icon: material/license
3+
---
4+
5+
# License
6+
7+
<!-- markdownlint-disable max-one-sentence-per-line -->
8+
9+
??? note "Apache 2 License"
10+
11+
```text
12+
{{ include_file('includes/repo/LICENSE-APACHE', 0, -1, 8) }}
13+
```
14+
15+
??? note "MIT License"
16+
17+
```text
18+
{{ include_file('includes/repo/LICENSE-MIT', 0, -1, 8) }}
19+
```

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

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
icon: material/security
3+
---
4+
5+
<!-- markdownlint-disable first-line-h1 -->
6+
<!-- markdownlint-disable required-headers -->
7+
{{ include_file('includes/repo/SECURITY.md') }}

‎docs/src/appendix/index.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
icon: material/file-document-plus-outline
3+
---
4+
5+
# Appendix
6+
7+
The appendix contains collections of extra information and examples relevant to Catalyst Voices.

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

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
icon: material/ballot
3+
---
4+
5+
<!-- markdownlint-disable MD025-->
6+
# Catalyst Ballot Format V1

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

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
icon: material/ballot-outline
3+
---
4+
5+
<!-- markdownlint-disable MD025-->
6+
# Catalyst Ballot Format V2

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

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
icon: material/ballot-recount-outline
3+
---
4+
5+
<!-- markdownlint-disable MD025-->
6+
# Catalyst Ballot Formats

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

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
status: new
2+
template: cip.html

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

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
icon: material/vote-outline

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

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

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

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
icon: material/pencil-box-multiple-outline
3+
---
4+
5+
<!-- markdownlint-disable MD025-->
6+
# Draft CIPs

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

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
icon: material/account-check

0 commit comments

Comments
 (0)