add easypage support

.github/workflows/check-build.yml

@@ -3,6 +3,7 @@ on: pull_request
 
 env:
   PYTHON_VERSION: 3.10.1
+  GH_TOKEN: ${{ secrets.GH_TOKEN }}
 
 jobs:
   check_build:
@@ -37,11 +38,14 @@ jobs:
         run: poetry install --no-interaction --no-root
 
       - name: Install Python dependencies
-        run: poetry install --no-interaction
+        run: |
+          poetry install --no-interaction
+          poetry run pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
 
       - name: Check docs build
         run: poetry run mkdocs build -s
 
+      # TODO: wanted to have rendered pages uploaded but those are over 60MB os will not fit in the free GH plan
       # - name: Archive docs artifacts
       #   uses: actions/upload-artifact@v2
       #   with:

.github/workflows/documentation.yml

@@ -6,6 +6,7 @@ on:
 
 env:
   PYTHON_VERSION: 3.10.1
+  GH_TOKEN: ${{ secrets.GH_TOKEN }}
 
 jobs:
   documentation:
@@ -40,7 +41,9 @@ jobs:
         run: poetry install --no-interaction --no-root
 
       - name: Install Python dependencies
-        run: poetry install --no-interaction
+        run: |
+          poetry install --no-interaction
+          poetry run pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
 
       - name: Deploy documentation
         run: |

docs/.pages

@@ -0,0 +1,3 @@
+nav:
+    - manual.md
+    - ...

docs/js/extra.js

@@ -1,7 +1,7 @@
-app.document$.subscribe(function() {
-  window.CI360.init();
-  var tables = document.querySelectorAll("article table")
-    tables.forEach(function(table) {
-      new Tablesort(table)
+document$.subscribe(function() {
+  var tables = document.querySelectorAll("article table:not([class])")
+  tables.forEach(function(table) {
+    new Tablesort(table)
   })
+  window.CI360.init();
 })

docs/manual.md

@@ -0,0 +1,34 @@
+---
+title: Example page
+icon: material/head-question
+eva: 
+    author:
+        display_name: Paweł Kucmus
+        url: https://github.com/pkucmus
+    description: | 
+        If you put a pipe `|` followed by a line break you can do a multiline description.
+        This supports markdown so you can put a:
+
+        - list
+        - image
+        - many other
+
+        Go to the [:material-github: source of this file](https://github.com/EVA-3D/contrib-extras/edit/main/docs/index.md) to see how it works.
+
+        Have fun: ![](assets/candy_bowl.png)
+    bom:
+        - name: my_custom_part
+          qty: 1
+          is_printable: true
+          url: assets/fake_stl.stl
+        - name: some screw
+          qty: 12
+          is_printable: false
+    eva_version: "2.0.0 and up"
+    print_instructions: | 
+        There are none, this is an example page
+    step_files: |
+        None
+---
+
+{% extends "easy_page.html" %}

eva_contrib_builder/plugin.py

@@ -0,0 +1,88 @@
+import logging
+
+from mkdocs.plugins import BasePlugin
+from mkdocs.exceptions import BuildError
+from mkdocs.utils.meta import YAML_RE
+import yaml
+try:
+    from yaml import CSafeLoader as SafeLoader
+except ImportError:  # pragma: no cover
+    from yaml import SafeLoader
+
+from eva_contrib_builder.schemas import EasyPageMeta
+
+
+log = logging.getLogger(__name__)
+
+
+
+# TODO: Decide if it's even helpful
+# import click
+# from mkdocs.__main__ import ColorFormatter
+# mkdocs_logger = logging.getLogger("mkdocs")
+# class GHActionsColorFormatter(ColorFormatter):
+
+#     PREFIX_LEVELS = {
+#         "WARNING": "::error::",
+#         "ERROR": "::error::",
+#     }
+
+#     def format(self, record):
+#         message = super().format(record)
+#         prefix = ""
+#         if record.levelname in self.PREFIX_LEVELS:
+#             prefix = self.PREFIX_LEVELS[record.levelname]
+#         return prefix + message
+# mkdocs_logger.handlers[0].setFormatter(GHActionsColorFormatter())
+
+class EVAContribPlugin(BasePlugin):
+
+    def on_config(self, config):
+        self.env = config['theme'].get_env()
+        self.env.filters["yes_no"] = self.yes_no
+
+    @staticmethod
+    def yes_no(value: bool):
+        return "yes" if value else "no"
+
+    def _get_markdown_context(self, page, config):
+        page.eva = None
+        if "eva" in page.meta:
+            page.eva = EasyPageMeta(**page.meta["eva"])
+
+        return {
+            "eva": page.eva,
+        }
+
+    def on_page_context(self, context, page, config, nav):
+        context = {**self._get_markdown_context(page, config), **context}
+        return context
+
+    def on_page_read_source(self, page, config):
+        # Mkdocs hides YAML parsing errors, to access those I need to load the 
+        # source and do an initial YAML load on my own, it get properly loded 
+        # again by mkdocs
+        try:
+            with open(page.file.abs_src_path, 'r', encoding='utf-8-sig', errors='strict') as f:
+                source = f.read()
+        except OSError:
+            log.error(f'File not found: {page.file.src_path}')
+            raise
+        except ValueError:
+            log.error(f'Encoding error reading file: {page.file.src_path}')
+            raise
+
+        m = YAML_RE.match(source)
+        if m:
+            try:
+                data = yaml.load(m.group(1), SafeLoader)
+                if not isinstance(data, dict):
+                    data = {}
+            except Exception as exc:
+                raise BuildError(f"Page's YAML metadata is malformed: {exc}")
+            page.meta = data
+        return source
+
+    def on_page_markdown(self, markdown, page, config, files):
+        md_template = self.env.from_string(markdown)
+        return md_template.render(**self._get_markdown_context(page, config))

eva_contrib_builder/schemas.py

@@ -0,0 +1,27 @@
+from typing import List, Optional
+from pydantic import BaseModel, Extra
+from pydantic.networks import HttpUrl
+
+
+class Author(BaseModel):
+    display_name: str
+    url: Optional[HttpUrl]
+
+
+class BOMItem(BaseModel):
+    name: str
+    qty: int
+    is_printable: bool
+    url: Optional[str]
+
+
+class EasyPageMeta(BaseModel):
+    author: Author
+    description: str
+    bom: List[BOMItem]
+    eva_version: str
+    print_instructions: str
+    step_files: Optional[str]
+
+    class Config:
+        extra = Extra.allow

mkdocs.yml

@@ -4,7 +4,7 @@ site_author: "Paweł Kucmus"
 site_description: "EVA 2 repository for the community to share their parts"
 edit_uri: ""
 
-copyright: Copyright © 2020 Paweł Kucmus
+copyright: Copyright © 2022 Paweł Kucmus
 
 repo_name: EVA-3D / contrib-extras
 repo_url: https://github.com/EVA-3D/contrib-extras
@@ -30,6 +30,7 @@ plugins:
   - search
   - minify:
       minify_html: true
+  - eva-contrib-plugin
 
 extra_css:
   - css/extra.css

overrides/easy_page.html

@@ -0,0 +1,43 @@
+{% block creator %}
+{% if eva.author.url %}
+> Created by: [{{ eva.author.display_name }}]({{ eva.author.url }})
+{% else %}
+> Created by: {{ eva.author.display_name }}
+{% endif %}
+{% endblock creator %}
+
+
+{% block description %}
+## Description
+{{ eva.description }}
+{% endblock description %}
+
+
+{% block bom %}
+## BOM
+
+| No | Qty | Name | Printable |
+| -- | --- | ---- | --------- |
+{% for item in eva.bom %}|{{loop.index}}|{{item.qty}}|{{item.name}}|{% if item.url %}[{{item.is_printable|yes_no}}]({{item.url}}){% else %}{{item.is_printable|yes_no}}{% endif %}|
+{% endfor %}
+{% endblock bom %}
+
+
+{% block compatibility %}
+## Compatible EVA Version
+{{ eva.eva_version }}
+{% endblock compatibility %}
+
+
+{% block instructions %}
+## Print instructions
+{{ eva.print_instructions }}
+{% endblock instructions %}
+
+
+{% block step_files %}
+{% if eva.step_files %}
+## Step Files
+{{ eva.step_files }}
+{% endif %}
+{% endblock step_files %}