0.9.0

.github/workflows/pdoc.yml

@@ -0,0 +1,47 @@
+name: docs site
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      # ADJUST THIS: install all dependencies (including pdoc)
+      - run: pip install -r requirements-dev.lock
+      # ADJUST THIS: build your documentation into docs/.
+      # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
+      - run: PDOC_GENERATING=1 pdoc -t doc/pdoc-template/ html_compose -o pdoc
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: pdoc/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/run-tests.yml

@@ -0,0 +1,38 @@
+name: run-tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'  # Adjust version as needed
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.lock
+
+      - name: Run linter
+        run: |
+          ruff check
+
+
+      - name: Run type checker
+        run: |
+          mypy src/html_compose/
+
+      - name: Run tests
+        run: |
+          pytest

.gitignore

@@ -9,6 +9,9 @@ wheels/
 # venv
 .venv
 
+# html docs
+pdoc/
+
 # spec read/generation
 tools/reference
 tools/spec_reference.json

README.md

@@ -133,7 +133,7 @@ a([tab]
               action=live.ShellCommand(
                   ["sass", "--update", "static/sass:static/css"]
               ),
-              no_reload=True,  # Nobody reads -these- files so we don't need to reload the server
+              reload=False,  # Nobody reads -these- files so we don't need to reload the server
           ),
           live.WatchCond(
               path_glob="./static/css/", 
@@ -216,8 +216,8 @@ Updates pertaining to those changes should be shipped into the actual module und
 
 # Dependencies
 
-- PalletsProjects [markupsafe](https://github.com/pallets/markupsafe/) for text escaping
-- `beautifulsoup4` to optionally beautify HTML
+- PalletsProjects [markupsafe](https://github.com/pallets/markupsafe/) for text escaping. Its "fast" implementation saves significant cycles in the sanitization process.
+- Optional: `beautifulsoup4` to beautify HTML
 
 # Development tools ⚙️
 

changelog.txt

@@ -1,3 +1,11 @@
+# 0.9.0
+This is primarly a documentation/automation patch.
+
+* Docs: build with pdoc. Automate with Github runner.
+* Improve and add more documentation
+* elements: move from elements.py to elements/name_element.py i.e. a_element.py
+* Export BaseAttribute directly from module
+
 # 0.8.1
 * WatchCond: Flip condition no_reload param -> reload param, with correct docstring
 

doc/ideas/02_base_element.md

@@ -1,4 +1,4 @@
-# Idea
+# Base Element
 
 The base element has tricks built into it so that you can write HTML faster.
 

doc/ideas/03_code_generator.md

@@ -1,5 +1,5 @@
-# Idea
-What if your editor had built in hinting around HTML properties?
+# Code Generator
+Idea: What if your editor had built in hinting around HTML properties?
 
 ## Implementation
 We take information from the HTML spec living document and MDN.
@@ -14,7 +14,7 @@ the `tools` directory contains:
 
 * `tools/generated/*_attrs.py` is the intermediate directory so runs do not write to source control directory, but you can see when a new change has happened.
 
-## Extension of this idea:
+<!-- ## Extension of this idea:
 TBD
 
-caniuse data can be used to generate warnings based on browser targets
+caniuse data can be used to generate warnings based on browser targets -->

doc/ideas/04_attrs.md

@@ -1,4 +1,4 @@
-# Idea
+# Attributes
 There are multiple ways to define attributes for an html element i.e.
 
 ```python

doc/ideas/05_livereload.md

@@ -1,11 +1,11 @@
-# Idea
+# Live Reload
 If it takes multiple steps to make a change, I'm going to make a change slowly.
 
 If I have to do nothing to notice my change immediately, I'm going to make changes quickly.
 
 The idea is to iterate rapidly, so we provide a generic tool to help you do just that.
 
-## Live Reload
+
 Live reload is an optional feature of html-compose to aid in rapid development.
 
 Browser based livereload is provided by 
@@ -58,8 +58,8 @@ live.server(
         live.WatchCond(
             "node-app/**/*.js",
             action=live.ShellCommand("./build.sh"),
-            # no_reload means not to try to reload the daemon
-            no_reload=True,
+            # no reload means not to try to reload the daemon or browser
+            reload=False,
         ),
         live.WatchCond(
             # Trigger reload when the bro