feat(docs): Improve cddl definitions (#294)

* fix(docs): Updated TODO place holder text with context * fix(docs): Render docs with better placeholder * docs(docs): Add more detail to proposal document specification * docs(docs): Add details to the Proposal Comment document * docs(docs): Add more proposal submission actions specifications * docs(docs): random cleanups * docs(docs): fix markdown lint issues * docs(docs): Use a CID for the document hash * docs(docs): Add document revocations to proposals and comments * docs(docs): turn hash into a map for better future proofing * docs(docs): Use defined cbor tag and binary format for IPLD Content Identifiers (CID) * docs(docs): Removed obsolete cddl definition * docs(docs): WIP cleanup and validaetg cddl defintions * docs(docs): Prep work to make it easier to generate CDDL files from specification * docs(docs): WIP cleanup of CDDL generation * docs(docs): Remove empty protected headers, as they can't be empty * feat(docs): Use latest draft cat-ci which supports relative file includes in mkdocs * fix(docs): cddl generation improvements * fix(docs): misc bug fixes * feat(Python): Make sure all python in the repo is properly formatted and linted. * fix(docs): spelling * docs(docs): Properly generalize document, signature and metadata headers * feat(docs): Make types.md generate under the new framework * feat(docs): Improve metadata docs, and generate individual cddl files for metadata definitions. * fix(docs): lint issue * fix(docs): cleanup spec deserialization to make accessing data easier for individual page documentation. * fix(docs): Make individual pages with the new spec generation framework * fix: remove now unused files * docs(docs): Add all the new docs generation stuff * docs(docs): Fix lint issues * fix(docs): one sentence mper link markdown fix * fix(docs): spell checking for dummys * fix(docs): remove dev file * fix(docs): Fix spec generation validation * fix(docs): Use latest cat-ci version * fix(docs): remove duplicated status on spec generation/validation * fix(docs): rename iana_media_types to just media_type * feat(docs): Also support CoAP encoded media types. * fix(docs): Properly constrain CoAP types to the known media types. --------- Co-authored-by: neil-iohk <neil.mcauliffe@iohk.io>

Author: stevenj

.config/dictionaries/project.dic

@@ -23,13 +23,15 @@ blosc
 bmac
 bootstrapper
 BROTLI
+Cabe
 cantopen
 cardano
 carryforward
 CBOR
 cbork
 cddlc
 cdylib
+CELLBORDER
 CEST
 chacha
 CHAINCODE
@@ -60,10 +62,13 @@ dbsync
 dcbor
 decompressor
 delegators
+direnv
 displaydoc
 dleq
 dlog
 dockerhub
+docstrings
+doctests
 Dominik
 dotenv
 dotenvy
@@ -76,6 +81,7 @@ encryptor
 Errno
 Eternl
 excalidraw
+explicitely
 extn
 fadvise
 fcntl
@@ -90,6 +96,7 @@ fmmap
 fmtchk
 fmtfix
 fontawesome
+fontname
 fromfiledate
 fsgr
 fstat
@@ -102,10 +109,12 @@ getres
 giantstep
 gmtime
 gossipsub
+graphviz
 happ
 hardano
 Hardlink
 hasher
+headlabel
 heaptrack
 hexdigit
 highwater
@@ -120,13 +129,16 @@ ioerr
 iohk
 ipfs
 ipld
+ipynb
+isort
 jetbrains
 jorm
 jormungandr
 Jörmungandr
 jsonschema
 Justfile
 kiduri
+labelloc
 lcov
 Leay
 Leshiy
@@ -168,6 +180,7 @@ MPMC
 msvc
 Multiaddr
 multiera
+mypy
 nanos
 netkey
 nextest
@@ -185,6 +198,7 @@ outlen
 Outparam
 outpubkey
 parameterises
+penwidth
 permissioned
 permissionless
 pg_isready
@@ -205,9 +219,17 @@ pubkey
 publickey
 pubspec
 pwrite
+pycodestyle
+pydantic
+pydot
+pyenv
+Pyflakes
+pypackages
 pytest
+pytype
 qpsg
 quic
+rankdir
 rapidoc
 readlinkat
 redoc
@@ -251,6 +273,7 @@ subsec
 symlinkat
 syscall
 tacho
+taillabel
 testcase
 testcov
 testdocs
@@ -267,6 +290,7 @@ tofiledate
 toobig
 toolsets
 Traceback
+tstr
 txmonitor
 txns
 typenum
@@ -282,6 +306,7 @@ utimensat
 UTXO
 uuidv4
 uuidv7
+venv
 vitss
 Vkey
 vkeywitness

Earthfile

@@ -1,8 +1,9 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/mdlint:v3.4.0 AS mdlint-ci
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/cspell:v3.4.0 AS cspell-ci
-
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/mdlint:v3.4.1 AS mdlint-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/cspell:v3.4.1 AS cspell-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/python:v3.4.1 AS python-ci
+IMPORT github.com/input-output-hk/catalyst-ci:v3.4.1 AS cat-ci
 
 FROM debian:stable-slim
 
@@ -42,9 +43,22 @@ repo-docs:
  COPY --dir *.md LICENSE-APACHE LICENSE-MIT .
 
  SAVE ARTIFACT /repo repo
+
+# We lint python globally in repos, so that all scripts and programs
+# are linted equally.
+# Its also fast.
+check-python:
+ DO python-ci+LINT_PYTHON 
+
+# Sync standard configs.
+sync-config:
+ FROM scratch
+ COPY --dir cat-ci+repo-config/repo .
+
+ SAVE ARTIFACT /repo/ruff.toml AS LOCAL ruff.toml
 
 # copy-specs : Copy the specs source folder.
 copy-specs:
  FROM scratch
  COPY --dir specs ./specs
- SAVE ARTIFACT /specs specs
+ SAVE ARTIFACT /specs specs

Justfile

@@ -21,7 +21,8 @@ format-python-code:
  ruff format .
 
 # Fix and Check Markdown files
-lint-python:
+lint-python: format-python-code
+ ruff check --fix .
  ruff check .
 
 # generates specifications data

docs/Earthfile

@@ -1,7 +1,6 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/docs:v3.4.0 AS docs-ci
-
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/docs:v3.4.1 AS docs-ci
 
 IMPORT .. AS repo
 

docs/src/appendix/important/license.md

@@ -9,11 +9,11 @@ icon: material/license
 ??? note "Apache 2 License"
 
  ```text
- {{ include_file('includes/repo/LICENSE-APACHE', 0, -1, 8) }}
+ {{ include_file('includes/repo/LICENSE-APACHE', indent=8) }}
  ```
 
 ??? note "MIT License"
 
  ```text
- {{ include_file('includes/repo/LICENSE-MIT', 0, -1, 8) }}
+ {{ include_file('includes/repo/LICENSE-MIT', indent=8) }}
  ```

docs/src/appendix/tags.md

@@ -4,4 +4,4 @@ icon: fontawesome/solid/tags
 
 # Tag Index
 
-[TAGS]
+<!-- material/tags -->

docs/src/architecture/08_concepts/catalyst_voting/cddl/Earthfile

@@ -1,6 +1,6 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.4.0 AS cddl-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/cddl:v3.4.1 AS cddl-ci
 
 check-cddl:
  FROM cddl-ci+cddl-base

docs/src/architecture/08_concepts/catalyst_voting/gen_vote_tx.md

@@ -27,7 +27,7 @@ Project "Catalyst" requires a structure to keep people vote's data in the secure
 ??? note "vote transaction definition: `gen_vote_tx.cddl`"
 
  ```CDDL
- {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/gen_vote_tx.cddl', indent=4) }}
+ {{ include_file('./cddl/gen_vote_tx.cddl', indent=4) }}
  ```
 <!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
 

docs/src/architecture/08_concepts/catalyst_voting/v1.md

@@ -29,7 +29,7 @@ An original Jörmungandr blockchain's `VoteCast` transaction structure.
 ??? note "V1 transaction definition: `jorm.abnf`"
 
  ```abnf
- {{ include_file('src/architecture/08_concepts/catalyst_voting/abnf/jorm.abnf', indent=4) }}
+ {{ include_file('./abnf/jorm.abnf', indent=4) }}
  ```
 <!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
 

docs/src/architecture/08_concepts/catalyst_voting/v2.md

@@ -60,7 +60,7 @@ Following that spec need to define a `choice`, `proof` and `prop-id`.
 ??? note "Public vote transaction v2 definition: `vote_tx_v2_public.cddl`"
 
  ```CDDL
- {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_public.cddl', indent=4) }}
+ {{ include_file('./cddl/vote_tx_v2_public.cddl', indent=4) }}
  ```
 <!-- markdownlint-enable max-one-sentence-per-line code-block-style -->
 
@@ -84,7 +84,7 @@ Following that spec need to define a `choice`, `proof` and `prop-id`.
 ??? note "Private vote transaction v2 definition: `vote_tx_v2_private.cddl`"
 
  ```CDDL
- {{ include_file('src/architecture/08_concepts/catalyst_voting/cddl/vote_tx_v2_private.cddl', indent=4) }}
+ {{ include_file('./cddl/vote_tx_v2_private.cddl', indent=4) }}
  ```
 <!-- markdownlint-enable max-one-sentence-per-line code-block-style -->