Add mkdocs-plugins docs

Author: RobertoPrevato

.github/workflows/main.yml

@@ -55,7 +55,7 @@ jobs:
           7z a -r site.zip blacksheep
 
       - name: Upload distribution package
-        uses: actions/upload-artifact@master
+        uses: actions/upload-artifact@v4
         with:
           name: dist
           path: .build/site.zip

.gitignore

@@ -4,5 +4,4 @@ venv
 .env
 
 # temporary
-mkdocs-plugins
 rodi

blacksheep/Makefile

@@ -19,20 +19,6 @@ build-v1:
 	echo "Ready to publish"
 
 
-# require env variables
-publish-dev:
-	PYAZ_ACCOUNT_KEY=${DEV_ACCOUNT_KEY} pyazblob upload --path .build/ --account-name "neoteroideveuwstacc" -cn "\$$web" -r -f
-
-
-publish-prod:
-	PYAZ_ACCOUNT_KEY=${PROD_EUW_ACCOUNT_KEY} pyazblob upload --path .build/ --account-name "neoteroieuwstacc" -cn "\$$web" -r -f
-	PYAZ_ACCOUNT_KEY=${PROD_USE_ACCOUNT_KEY} pyazblob upload --path .build/ --account-name "neoteroieusstacc" -cn "\$$web" -r -f
-
-
-fixlinks:
-	./fixlinks.sh
-
-
 clean:
 	rm -rf site/
 	rm -rf .build/

mkdocs-plugins/.gitignore

@@ -0,0 +1,7 @@
+.env
+.build
+logs
+site
+
+venv
+venv2

mkdocs-plugins/README.md

@@ -0,0 +1,5 @@
+# mkdocs-plugins-docs
+Repository containing the documentation of mkdocs-plugins.
+
+* [DEV](https://neoteroideveuwstacc.z6.web.core.windows.net/mkdocs-plugins/)
+* [PROD](https://www.neoteroi.dev/mkdocs-plugins/)

mkdocs-plugins/debug.py

@@ -0,0 +1,6 @@
+"""
+Run this module to debug a plugin.
+"""
+from mkdocs.commands import serve
+
+serve.serve(dev_addr="localhost:44555", livereload=True)

mkdocs-plugins/dev/convert.py

@@ -0,0 +1,73 @@
+"""
+Utility to convert examples from one format to another.
+
+Example:
+python convert.py to-yaml ../docs/timeline/timeline-1.json ../docs/timeline/timeline-1.yaml
+"""
+import json
+import re
+import sys
+from typing import Optional
+
+import click
+import yaml
+from essentials.json import dumps as friendly_json_dumps
+
+_YAML_EXT = re.compile(r"\.ya?ml$", re.IGNORECASE)
+_JSON_EXT = re.compile(r"\.json$", re.IGNORECASE)
+
+
+def read_text_file(file_path: str) -> str:
+    with open(file_path, "rt", encoding="utf8") as source_file:
+        return source_file.read()
+
+
+def write_text_file(file_path: str, contents: str):
+    with open(file_path, "wt", encoding="utf8") as dest_file:
+        dest_file.write(contents)
+
+
+@click.group()
+def convert():
+    pass
+
+
+@click.command("to-json")
+@click.argument("source")
+@click.argument("destination", required=False)
+def yaml_to_json(source: str, destination: Optional[str]):
+    if _YAML_EXT.search(source):
+        contents = read_text_file(source)
+        data = yaml.safe_load(contents)
+        output = friendly_json_dumps(data, indent=4, ensure_ascii=False)
+        if destination:
+            write_text_file(destination, output)
+        else:
+            print(output)
+    else:
+        click.echo(f'Unsupported source: "{source}"')
+        sys.exit(1)
+
+
+@click.command("to-yaml")
+@click.argument("source")
+@click.argument("destination", required=False)
+def json_to_yaml(source: str, destination: Optional[str]):
+    if _JSON_EXT.search(source):
+        contents = read_text_file(source)
+        data = json.loads(contents)
+        if destination:
+            write_text_file(destination, yaml.dump(data))
+        else:
+            print(yaml.dump(data))
+    else:
+        click.echo(f'Unsupported source: "{source}"')
+        sys.exit(1)
+
+
+convert.add_command(yaml_to_json)
+convert.add_command(json_to_yaml)
+
+
+if __name__ == "__main__":
+    convert()

mkdocs-plugins/docs/about.md

@@ -0,0 +1,8 @@
+# About Neoteroi
+
+[Neoteroi](https://github.com/Neoteroi/) is a collection of projects for Python.
+
+## The project's home
+The project source code is in [GitHub](https://github.com/Neoteroi/mkdocs-plugins).
+
+The documentation source code is in [GitHub](https://github.com/Neoteroi/mkdocs-plugins-docs).