feat: Add documentation auto generation for new signed documents

Author: stevenj

.config/dictionaries/project.dic

@@ -202,6 +202,7 @@ pubkey
 publickey
 pubspec
 pwrite
+pytest
 qpsg
 quic
 rapidoc

.gitignore

@@ -84,3 +84,6 @@ $RECYCLE.BIN/
 # Dart stuff
 /pubspec.lock
 /.dart_tool/**/*
+
+# Python stuff
+.pytest_cache

.markdownlint-cli2.jsonc

@@ -10,7 +10,8 @@
   "ignores": [
     ".config/dictionaries/**",
     "**/target/**",
-    "**/.dart_tool/**"
+    "**/.dart_tool/**",
+    "**/.pytest_cache/**"
   ],
   // Set standard config options in `/.markdownlint.jsonc`
   "config": {

Justfile

@@ -15,6 +15,19 @@ check-spelling:
     earthly +check-spelling
 
 
+# Fix and Check Markdown files
+format-python-code:
+    ruff check --select I --fix .
+    ruff format .
+
+# Fix and Check Markdown files
+lint-python:
+    ruff check .
+
+# generates specifications data
+gen_specs:
+    just specs/pre-push
+
 # Pre Push Checks - intended to be run by a git pre-push hook.
-pre-push: check-markdown check-spelling
+pre-push: gen_specs check-markdown check-spelling format-python-code lint-python
     just rust/pre-push

docs/macros/__init__.py

@@ -1,5 +1,6 @@
 from .include import inc_file
-from .signed_docs import (doc_type_summary, doc_type_details)
+from .signed_docs import doc_type_details, doc_type_summary, signed_doc_details
+
 
 def define_env(env):
     """
@@ -18,3 +19,7 @@ def insert_doc_type_summary():
     @env.macro
     def insert_doc_type_details():
         return doc_type_details(env)
+
+    @env.macro
+    def insert_signed_doc_details(name):
+        return signed_doc_details(env, name)

docs/macros/signed_docs.py

@@ -1,10 +1,12 @@
-import os
-import re
-import textwrap
 import json
+import os
+
+# import re
+# import textwrap
+
+# SIGNED_DOCS_SPECS="signed_doc.json"
+SIGNED_DOCS_SPECS = "includes/signed_doc.json"
 
-#SIGNED_DOCS_SPECS="signed_doc.json"
-SIGNED_DOCS_SPECS="includes/signed_doc.json"
 
 def uuid_as_cbor(uuid):
     return f"37(h'{uuid.replace('-', '')}')"
@@ -19,6 +21,7 @@ def get_signed_doc_data(env):
     with open(full_filename, "r") as f:
         return json.load(f)
 
+
 def doc_type_summary(env):
     """
     Generate a Document Base Type Summary from the Document Specifications Data
@@ -34,7 +37,9 @@ def doc_type_summary(env):
 """
 
         for k in doc_types:
-            doc_type_summary += f"| {k} | `{doc_types[k]}` | `{uuid_as_cbor(doc_types[k])}` |\n"
+            doc_type_summary += (
+                f"| {k} | `{doc_types[k]}` | `{uuid_as_cbor(doc_types[k])}` |\n"
+            )
 
         return doc_type_summary
     except Exception as exc:
@@ -50,23 +55,25 @@ def name_for_uuid(doc_types, uuid):
             return k
     return "Unknown"
 
-               
-def name_to_spec_link(name,ref=None):
+
+def name_to_spec_link(name, ref=None):
     """
     Create a link to a document type, and an optional ref inside the document.
     """
-    link = "./../catalyst_docs/"+name.lower().replace(' ','_') + ".md"
+    link = "./../catalyst_docs/" + name.lower().replace(" ", "_") + ".md"
     if ref is not None:
         link += f"#{ref}"
     return link
 
+
 def base_types(docs, doc_types, name):
     types = docs[name]["type"]
     type_names = ""
     for sub_type in types:
         type_names += name_for_uuid(doc_types, sub_type) + "/"
     return type_names[:-1]
 
+
 def types_as_cbor(docs, name):
     types = docs[name]["type"]
     type_names = "["
@@ -91,16 +98,24 @@ def doc_type_details(env):
 """
 
         for k in docs:
-            doc_type_details += f"| {k} | {base_types(docs,doc_types,k)} | {types_as_cbor(docs,k)} | [Specification]({name_to_spec_link(k)}) | \n"
+            doc_type_details += f"| {k} | {base_types(docs, doc_types, k)} | {types_as_cbor(docs, k)} | [Specification]({name_to_spec_link(k)}) | \n"
 
         return doc_type_details
     except Exception as exc:
         return f"{exc}"
 
-#class env:
+
+def signed_doc_details(env, name):
+    """
+    Generate Signed Document Detailed Documentation Page.
+    """
+    return name + "\n" + "test\n"
+
+
+# class env:
 #    project_dir = "/home/steven/Development/iohk/catalyst-libs/specs"
 
-#if __name__ == '__main__':
+# if __name__ == '__main__':
 
-#    print(doc_type_details(env))    
-#    print(doc_type_summary(env))
+#    print(doc_type_details(env))
+#    print(doc_type_summary(env))

docs/src/architecture/08_concepts/catalyst_docs/.pages

@@ -1,5 +1 @@
 title: Catalyst Documents
-arrange:
-- proposal.md
-- review.md
-- comment.md

docs/src/architecture/08_concepts/catalyst_docs/category_parameters.md

@@ -1 +1 @@
-# Category Parameters
+# {{ insert_signed_doc_details( "Category Parameters" ) }}

docs/src/architecture/08_concepts/catalyst_docs/comment_action_document.md

@@ -1 +1 @@
-# Comment Action Document
+# {{ insert_signed_doc_details( "Comment Action Document" ) }}