docs(docs): Split mkdocs into a controlled theme and doc specific parts.

Better align the docs earthfile structure with the style guide

docs/Earthfile

@@ -2,14 +2,14 @@ VERSION 0.7
 
 # Copy all the source we need to build the docs
 src:
-    FROM ../earthly/docs+mkdocs-material
-
-    # Just copy the actual doc src here.
-    COPY --dir src includes macros overrides mkdocs.yml /docs
+    # Common src setup
+    DO ../earthly/docs+SRC
 
     # Now copy into that any artifacts we pull from the builds.
     COPY --dir ../+repo-docs/repo /docs/includes
 
+    RUN ls -al /docs
+
 
 # Build the docs here.
 docs:
@@ -25,4 +25,14 @@ local:
 
     COPY +docs/ /usr/share/nginx/html
 
-    SAVE IMAGE cat-ci-docs:latest
+    SAVE IMAGE cat-ci-docs:latest
+
+# Documentation files used across all documentation builds.
+common:
+    #FROM scratch
+    FROM alpine:3.18
+
+    COPY --dir std-theme.yml includes macros overrides /std
+    RUN ls -al /std
+
+    SAVE ARTIFACT /std

docs/mkdocs.yml

@@ -1,119 +1,13 @@
-# cspell: words Diagramsnet, pymdownx, linenums, inlinehilite, superfences,
-# cspell: words tasklist, betterem, materialx, twemoji, smartsymbols,
-# cspell: words kroki, excalidraw, glightbox, cips, pygments, arithmatex
+INHERIT: std-theme.yml
 
 # Project Information
-site_name: Project Catalyst - Catalyst CI Documentation
+site_name: Project Catalyst - CI Documentation
 site_url: https://input-output-hk.github.io/catalyst-ci
-site_author: The Project Catalyst Team
-copyright: (c) 2023 Input Output
 
 # Repository
 repo_name: input-output-hk/catalyst-ci
 repo_url: https://github.com/input-output-hk/catalyst-ci
 
-# The Documentation src to build.
-docs_dir: src
-
-theme:
-  name: material
-  custom_dir: overrides
-  palette:
-    # Palette toggle for light mode
-    - scheme: default
-      media: "(prefers-color-scheme: light)"
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-
-    # Palette toggle for dark mode
-    - scheme: slate
-      media: "(prefers-color-scheme: dark)"
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
-
-  features:
-    - navigation.instant
-    - navigation.instant.progress
-    - navigation.tracking
-    #- navigation.tabs
-    #- navigation.tabs.sticky
-    - navigation.sections
-    - navigation.expand
-    - navigation.path
-    - navigation.indexes
-    - toc.follow
-    - toc.integrate
-    - search.suggest
-    - search.highlight
-
-plugins:
-  - search
-  - meta-manager
-  - macros:
-      module_name: macros
-  # - diagrams - Plugin is installed, but produces corrupted output
-  - kroki:
-      ServerURL: https://kroki.io
-      EnableDiagramsnet: true
-      HttpMethod: POST
-  - glightbox
-
-markdown_extensions:
-  # Python Markdown
-  - abbr
-  - admonition
-  - attr_list
-  - def_list
-  - footnotes
-  - md_in_html
-  - tables
-  - toc:
-      permalink: true
-
-  # Python Markdown Extensions
-  - pymdownx.arithmatex:
-      generic: true
-  - pymdownx.betterem:
-      smart_enable: all
-  - pymdownx.caret
-  - pymdownx.details
-  - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
-  - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-  - pymdownx.inlinehilite
-  - pymdownx.keys
-  - pymdownx.mark
-  - pymdownx.smartsymbols
-  - pymdownx.snippets:
-      auto_append:
-        - includes/abbreviations.md
-  - pymdownx.superfences:
-      custom_fences:
-        - name: mermaid
-          class: mermaid
-          format: !!python/name:pymdownx.superfences.fence_code_format
-  - pymdownx.tabbed:
-      alternate_style: true
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  - pymdownx.tilde
-
-extra:
-  consent:
-    title: Cookie consent
-    description: >-
-
-      We use cookies to recognize your repeated visits and preferences, as well
-      as to measure the effectiveness of our documentation and whether users
-      find what they're searching for. With your consent, you're helping us to
-      make our documentation better.
-
 # Page tree
 nav:
   - Introduction: index.md

docs/std-theme.yml

@@ -0,0 +1,108 @@
+# cspell: words Diagramsnet, pymdownx, linenums, inlinehilite, superfences,
+# cspell: words tasklist, betterem, materialx, twemoji, smartsymbols,
+# cspell: words kroki, excalidraw, glightbox, cips, pygments, arithmatex
+
+site_author: The Project Catalyst Team
+copyright: (c) 2023 Input Output Global Ltd.
+
+# The Documentation src to build.
+docs_dir: src
+
+theme:
+  name: material
+  custom_dir: overrides
+  palette:
+    # Palette toggle for light mode
+    - scheme: default
+      media: "(prefers-color-scheme: light)"
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - scheme: slate
+      media: "(prefers-color-scheme: dark)"
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  features:
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.tracking
+    #- navigation.tabs
+    #- navigation.tabs.sticky
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.indexes
+    - toc.follow
+    - toc.integrate
+    - search.suggest
+    - search.highlight
+
+plugins:
+  - search
+  - meta-manager
+  - macros:
+      module_name: macros
+  # - diagrams - Plugin is installed, but produces corrupted output
+  - kroki:
+      ServerURL: https://kroki.io
+      EnableDiagramsnet: true
+      HttpMethod: POST
+  - glightbox
+
+markdown_extensions:
+  # Python Markdown
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+
+  # Python Markdown Extensions
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      auto_append:
+        - includes/abbreviations.md
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra:
+  consent:
+    title: Cookie consent
+    description: >-
+
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.

earthly/docs/Earthfile

@@ -1,9 +1,9 @@
 VERSION 0.7
-FROM python:3.12-alpine3.18
 
 # cspell: words libgcc freetype lcms openjpeg
 
-mkdocs-material:
+deps:
+    FROM python:3.12-alpine3.18
     # Derived from official mkdocs-material docker container.
     # https://github.com/squidfunk/mkdocs-material/blob/master/Dockerfile
     # Due to docs being constructed not only from Doc source but Build artifacts,
@@ -45,14 +45,21 @@ mkdocs-material:
     # Set working directory
     WORKDIR /docs
 
-    # Live Docs are not supported, this is only used during testing.
 
-    # Expose MkDocs development server port
-    EXPOSE 8000
+# Common src setup
+SRC:
+    COMMAND
+
+    FROM +deps
+
+    COPY ../../docs+common/* /docs
+
+    # Just copy the actual doc src here.
+    COPY --dir src mkdocs.yml /docs
+
+    # Any files which replace the standard files are copied here
+    COPY --if-exists --dir includes macros overrides  /docs
 
-    # Start development server by default
-    # Will live serve the docs in `/docs` on 0.0.0.0:8000
-    ENTRYPOINT ["/scripts/serve.sh"]
 
 # Build the docs - We always do this in a `docs` target.  
 # The only target that needs customizing is the `src` target.
@@ -83,7 +90,7 @@ PACKAGE:
     CMD ["nginx", "-g", "daemon off;"]
 
     # These steps are done outside the UDC.
-    
+
     # Copy the static pages into the container like this...
     #COPY $docs /usr/share/nginx/html