fix(python): make document inclusion in docs allow relative paths. (#395)

* fix(python): Python Lints.

* fix(python): Fix comment in Justfile

* fix(python): spelling fixes

* fix(python): Remove subprocess._ENV it doesn't exist...

* fix(python): name named parameters

* fix(python): Name non positional parameters

* fix(python): disable lints for print

* fix(python): fix more bool flags

* fix(python): Its ok if the docs dir exists

* fix(python): bin was renamed to bin_file

* fix(python): filename needs to be a string not a path

* fix(python): Make `indent` default to 0, not None.

* fix(python): Use relative includes for files in sub directories.

* docs(python): Update mkdocs and fix relative includes.

* fix(python): Bump to python 13

* fix(python): update dependencies as it no longer builds

* fix(python): update docs

* fix(python): add UV to base python builder

* fix(python): Add UV to the path

Author: stevenj

.config/dictionaries/project.dic

@@ -14,7 +14,10 @@ cytopia
 depgraph
 devenv
 dind
+direnv
 dockerhub
+docstrings
+doctests
 doseq
 doublecircle
 Earthfile
@@ -48,6 +51,7 @@ gopls
 gosec
 graphviz
 idents
+ipynb
 JDBC
 jorm
 jormungandr
@@ -90,7 +94,9 @@ projectcatalyst
 pubout
 pubspec
 pymdownx
+pypackages
 PYTHONDONTWRITEBYTECODE
+pytype
 rankdir
 rivo
 runewidth

Earthfile

@@ -4,6 +4,7 @@ IMPORT ./earthly/mdlint AS mdlint-ci
 IMPORT ./earthly/cspell AS cspell-ci
 IMPORT ./earthly/bash AS bash-ci
 IMPORT ./earthly/spectral AS spectral-ci
+IMPORT ./earthly/python AS python-ci
 
 # cspell: words livedocs sitedocs
 
@@ -49,6 +50,7 @@ repo-config:
 
     WORKDIR /repo
     COPY --dir .sqlfluff .
+    COPY --dir ruff.toml .
 
     SAVE ARTIFACT /repo repo
 
@@ -57,4 +59,9 @@ edit-docs:
     LOCALLY
 
     RUN ./earthly/docs/dev/local.py cat-ci-docs:latest
-    
+
+# 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    

Justfile

@@ -1,12 +1,10 @@
 # use with https://github.com/casey/just
 #
-
-# cspell: words prereqs, commitlog
+# Developer convenience functions
 
 default:
     @just --list --unsorted
 
-
 # Fix and Check Markdown files
 check-markdown:
     earthly +markdown-check-fix
@@ -17,14 +15,19 @@ check-spelling:
     earthly +check-spelling
 
 
-# Fix and Check Markdown files
+# Fix and Check Code Format for Python files
 format-python-code:
     ruff check --select I --fix .
     ruff format .
 
-# Fix and Check Markdown files
-lint-python:
+# Fix and Check Lint for Python files
+lint-python: format-python-code
+    ruff check --fix .
     ruff check .
 
 # Pre Push Checks - intended to be run by a git pre-push hook.
 pre-push: check-markdown check-spelling format-python-code lint-python
+
+# Preview docs locally
+preview-docs:
+    earthly/docs/dev/local.py cat-ci-docs:latest

docs/includes/abbreviations.md

@@ -0,0 +1,3 @@
+<!-- markdownlint-disable MD041 MD043-->
+*[HTML]: Hyper Text Markup Language
+*[W3C]: World Wide Web Consortium

docs/src/appendix/examples/abbreviations.md

@@ -11,3 +11,13 @@ The HTML Specification is maintained by the W3C.
 !!! note
 
     Abbreviations go in the `docs/includes/abbreviations.md` file.
+    Except that doesn't work for some reason...
+    So embed them like this at the end of a document:
+
+    ```md
+    *[HTML]: Hyper Text Markup Language
+    *[W3C]: World Wide Web Consortium
+    ```
+
+*[HTML]: Hyper Text Markup Language
+*[W3C]: World Wide Web Consortium

docs/src/appendix/examples/d2-diagrams.md

@@ -29,11 +29,11 @@ example:
 This is the sample valid CQL schema code:
 
 ```cql
-{{ include_file('src/appendix/examples/diagrams/sample_d2.cql') }}
+{{ include_file('./diagrams/sample_d2.cql') }}
 ```
 
 Resulted in D2:
 
 ```d2
-{{ include_file('src/appendix/examples/diagrams/sample_d2.d2') }}
+{{ include_file('./diagrams/sample_d2.d2') }}
 ```

docs/src/appendix/examples/graphviz-diagrams.md

@@ -7,9 +7,9 @@ icon: material/draw
 ## Graphviz SVG's
 
 === "Trees"
-<!-- markdownlint-disable no-inline-html -->
+    <!-- markdownlint-disable no-inline-html -->
     <center>
-<!-- markdownlint-enable no-inline-html -->
+    <!-- markdownlint-enable no-inline-html -->
 
     ```dot
     graph G {
@@ -150,21 +150,21 @@ icon: material/draw
 ???- note "graphviz in UnExpanded Block"
 
     ```dot
-    {{ include_file('src/appendix/examples/diagrams/invasion_plan.dot', indent=4) }}
+    {{ include_file('./diagrams/invasion_plan.dot', indent=4) }}
     ```
 
 ???+ note "graphviz in Expanded Block"
 
     ```dot
-    {{ include_file('src/appendix/examples/diagrams/invasion_plan.dot', indent=4) }}
+    {{ include_file('./diagrams/invasion_plan.dot', indent=4) }}
     ```
 
 ## Graphviz PNG's (lower quality than SVGs)
 
 === "Graphviz Render"
 
     ```graphviz dot attack_plan.png
-    {{ include_file('src/appendix/examples/diagrams/invasion_plan.dot', indent=4) }}
+    {{ include_file('./diagrams/invasion_plan.dot', indent=4) }}
     ```
 
 === "Example of Code Syntax"
@@ -173,6 +173,6 @@ icon: material/draw
 
     ~~~
     ``` graphviz dot attack_plan.png
-    {{ include_file('src/appendix/examples/diagrams/invasion_plan.dot', indent=4) }}
+    {{ include_file('./diagrams/invasion_plan.dot', indent=4) }}
     ```
     ~~~

docs/src/appendix/examples/kroki-diagrams.md

@@ -4,9 +4,7 @@ icon: material/draw
 
 # Mermaid Diagrams
 
-There is overlap between Kroki and Mermaid
-
-Mermaid can not zoom, but it can embed links.
+Mermaid diagrams can be embedded inline.
 
 ``` mermaid
 graph LR

docs/src/appendix/examples/mermaid-diagrams.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) }}
     ```