Add mkdocs plugin (#12)

.github/workflows/ci.yml

@@ -122,7 +122,7 @@ jobs:
         with:
           pixi-version: v${{ env.URLJSF_PIXI_VERSION }}
           cache: true
-          environments: build docs check atest
+          environments: atest build check docs test
           cache-key: job-docs
       - name: cache (node)
         uses: actions/cache@v4

.gitignore

@@ -8,3 +8,4 @@ dist/
 lib/
 node_modules/
 src/urljsf/_static
+tests/fixtures/mkdocs/*/site

CHANGELOG.md

@@ -1,9 +1,11 @@
 # Changelog
 
-## 0.1.1
+> ## 0.1.1 (Unreleased)
+>
+> - [#12] adds an `mkdocs` plugin, available with `urljsf[mkdocs]`
+>
+> [#12]: https://github.com/deathbeds/urljsf/pull/12
 
-> TBD
-
-## 0.1.0
+## [0.1.0](https://github.com/deathbeds/urljsf/releases/tag/v0.1.0)
 
 - initial release

README.md

@@ -48,7 +48,7 @@ Once the data is _validated_, the user sees a button which gets a URL, which can
 
 - a drop-in-and-pray [`script`](#js-script)
 - a standalone [CLI tool](#command-line)
-- a [sphinx](#sphinx) extension
+- a [`sphinx`](#sphinx) or [`mkdocs`](#mkdocs) extension
 
 ... to create JavaScript/HTML forms that helps **visitors** provide good data for:
 
@@ -66,32 +66,37 @@ Once the data is _validated_, the user sees a button which gets a URL, which can
 
 ### From PyPI
 
-`urljsf` is distributed on [PyPI][pypi]:
+`urljsf` is distributed on [PyPI][pypi], with several optional extras to help ensure
+tested versions are available:
 
 ```bash
 pip install urljsf
+# ... or    urljsf[sphinx]   for sphinx
+# ... or    urljsf[mkdocs]   for mkdocs and pymdown-extensions
+# ... or    urljsf[yaml]     for build time YAML parsing
 
 # or...
 uv install urljsf
-
 # etc.
 ```
 
 ### From conda-forge
 
-`urljsf` is also distributed on [`conda-forge`][conda]:
+`urljsf` is also distributed on [`conda-forge`][conda], with similar extras:
 
 ```bash
 pixi add urljsf
+# ... or urljsf-with-sphinx
+# ... or urljsf-with-mkdocs
+# ... or urljsf-with-yaml
 
 # or...
 micromamba install -c conda-forge urljsf
-
 # or...
 mamba install -c conda-forge urljsf
-
 # or...
 conda install -c conda-forge urljsf
+# etc.
 ```
 
 ### Development
@@ -104,7 +109,7 @@ See the [contributing guide][contrib] for a development install.
 
 - (not-recommended) hot-linked [`script`](#js-script)
 - a standalone [site generator](#command-line) for simple sites
-- a [plugin](#sphinx) for the `sphinx` documentation system
+- a plugin for the [`sphinx`](#sphinx) and [`mkdocs`](#mkdocs) documentation systems
 
 ### JSON Schema
 
@@ -148,7 +153,8 @@ Some ways to improve:
 - download a GitHub release and unpack it, serving the files next to it
 - ensure bootstrap is loaded _before_ the script, with a `link` tag in a `head`.
 - on the `script` element, use a `src` to point to a valid `urljsf` definition
-- use the [CLI](#command-line) or [Sphinx extension](#sphinx)
+- use the [CLI](#command-line) or a documentation extension for [`sphinx`](#sphinx) or
+  [`mkdocs`](#mkdocs)
 
 ### Command Line
 
@@ -167,7 +173,8 @@ the [documentation][cli-docs] for more.
 
 ### Sphinx
 
-After [installing](#install), add `urljsf.sphinxext` to `conf.py`:
+After [installing](#install) with the `[sphinx]` extra, add `urljsf.sphinxext` to
+`conf.py`:
 
 ```py
 # conf.py
@@ -190,13 +197,41 @@ See the [documentation][sphinx-docs] for more about configuring `urljsf.sphinxex
 
 [sphinx-docs]: https://urljsf.rtfd.org/en/latest/use/sphinx.html
 
+### Mkdocs
+
+After [installing](#install) with the `[mkdocs]` extra, add `urljsf` to `mkdocs.yml`:
+
+```yaml
+# mkdocs.yml
+plugins:
+  - urljsf
+```
+
+Then use the `urljsf` fenced code block in source files:
+
+````markdown
+```urljsf {path=path/to/defnition.toml}
+
+```
+````
+
+See the [documentation][mkdocs-docs] for more about configuring `urljsf`, the `urljsf`
+fence, and more advanced use cases.
+
+[mkdocs-docs]: https://urljsf.rtfd.org/en/latest/use/mkdocs.html
+
 ## Limitations
 
 - `react-json-schema-form` cannot represent all possible data structures, such as
   writing a _new_ JSON schema _in_ JSON schema, or many features added after Draft 7
 - the generated scripts _won't_ work when served from `file://` due to browser CORS
   headers requirements for `type="module"` scripts
-- the [`sphinx`](#sphinx) integration is only tested with the `html` builder
+- the [`sphinx`](#sphinx) integration is only tested with the `html` builder, the basic
+  `alabaster` theme, and [`pydata-sphinx-theme`][pdst] (by way of `urljsf`'s own
+  [documentation][sphinx-docs])
+- the [`mkdocs`](#mkdocs) integration is only tested with the default theme
+
+[pdst]: https://github.com/pydata/pydata-sphinx-theme
 
 ## Open Source
 

atest/libraries/server.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import argparse
 import asyncio
 import logging
 import shutil
@@ -60,20 +61,32 @@ def get_unused_port() -> int:
     return port
 
 
+def get_parser() -> argparse.ArgumentParser:
+    """Parse command line options."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int)
+    parser.add_argument("--docs")
+    parser.add_argument("--patch")
+    parser.add_argument("--dist-cov")
+    parser.add_argument("--mkdocs")
+    return parser
+
+
 def main(argv: list[str] | None = None) -> int:
     """Parse args and run the server until shutdown."""
-    port, static, patch, dist_cov = argv or sys.argv[1:]
+    args = get_parser().parse_args(argv)
 
     with tempfile.TemporaryDirectory() as td:
         tdp = Path(td)
         www = tdp / "www"
-        assets = www / patch
-        shutil.copytree(static, www)
+        assets = www / args.patch
+        shutil.copytree(args.docs, www)
         shutil.rmtree(assets)
-        shutil.copytree(dist_cov, assets)
+        shutil.copytree(args.dist_cov, assets)
+        shutil.copytree(args.mkdocs, www / "mkdocs")
 
         asyncio.new_event_loop().run_until_complete(
-            start_http_server(int(port), str(www))
+            start_http_server(args.port, str(www))
         )
 
         shutil.rmtree(td, ignore_errors=True)

atest/resources/env.resource

@@ -28,4 +28,5 @@ ${TIMEOUT_LONG}     10s
 ${BUILD}            ${ROOT}${/}build
 ${DOCS}             ${BUILD}${/}docs
 ${DIST_COV}         ${BUILD}${/}dist-cov${/}urljsf
+${BUILD_MKDOCS}     ${BUILD}${/}mkdocs
 ${DOWNLOADS}        ${OUTPUT_DIR}${/}Downloads

atest/resources/server.resource

@@ -12,7 +12,12 @@ Start Server
     [Documentation]    Start an HTTP server.
     ${port} =    Get Unused Port
     ${server} =    Start Process
-    ...    python    ${SERVER_PY}    ${port}    ${DOCS}    ${STATIC_ASSETS}    ${DIST_COV}
+    ...    python    ${SERVER_PY}
+    ...    --port    ${port}
+    ...    --docs    ${DOCS}
+    ...    --patch    ${STATIC_ASSETS}
+    ...    --dist-cov    ${DIST_COV}
+    ...    --mkdocs    ${BUILD_MKDOCS}
     ...    stdout=${OUTPUT_DIR}${/}http.log
     ...    stderr=STDOUT
     Set Suite Variable    ${HTTP_PORT}    ${port}    children=${TRUE}

atest/resources/urljsf.resource

@@ -33,11 +33,16 @@ Open Page
     Go To    ${HTTP_URL}/${page}
     Wait Until Element Is Visible    css:${CSS_U_FORM}    timeout=${TIMEOUT_LONG}
 
-Open Demo
+Open Sphinx Demo
     [Documentation]    Open a named demo.
     [Arguments]    ${demo}
     Open Page    demos/${demo}.html
 
+Open Mkdocs Page
+    [Documentation]    Open a page in mkdocs demo.
+    [Arguments]    ${page}
+    Open Page    mkdocs/${page}/index.html
+
 Scroll To
     [Documentation]    Scroll the first element matching a CSS selector into view.
     [Arguments]    ${css_selector}

atest/resources/xkcd.resource

@@ -0,0 +1,50 @@
+*** Settings ***
+Documentation       XKCD demo keywords
+
+Resource            ../resources/urljsf.resource
+Library             SeleniumLibrary
+
+
+*** Variables ***
+${SLIDER_ID}    urljsf-0-url_xkcd
+
+
+*** Keywords ***
+Exercise XKCD Demo
+    [Documentation]    Run through the basic steps of the XKCD demo
+    Wait Until Element Is Visible    css:${CSS_U_FORM}
+    Capture Element Screenshot    css:${CSS_U_FORM}    00-open.png
+    ${n} =    Verify XKCD Value Changes
+    Capture Element Screenshot    css:${CSS_U_FORM}    01-changed.png
+    Verify XKCD URL    ${n}
+
+Verify XKCD Value Changes
+    [Documentation]    Verify the slider changes.
+    ${old} =    Get XKCD Number
+    Change XKCD
+    ${new} =    Get XKCD Number
+    Should Not Be Equal    ${old}    ${new}
+    RETURN    ${new}
+
+Change XKCD
+    [Documentation]    Change a slider value
+    Click Element    css:#${SLIDER_ID}
+    Click Element At Coordinates    css:#${SLIDER_ID}    -100    0
+
+Get XKCD Number
+    [Documentation]    Get a slider value.
+    ${xkcd} =    Get Element Attribute    css:#${SLIDER_ID}    value
+    RETURN    ${xkcd}
+
+Get XKCD URL
+    [Documentation]    Get the submit value.
+    ${url} =    Get Element Attribute    css:${CSS_U_SUBMIT}    href
+    RETURN    ${url}
+
+Verify XKCD URL
+    [Documentation]    Verify the URL against an expected value.
+    [Arguments]    ${n}
+    ${expect} =    Set Variable    https://xkcd.com/${n}
+    ${url} =    Get Element Attribute    css:${CSS_U_SUBMIT}    href
+    Capture Element Screenshot    css:${CSS_U_FORM}    02-slid.png
+    Should Be Equal As Strings    ${url}    ${expect}

atest/suites/00_jsdemo.robot

@@ -1,53 +1,17 @@
 *** Settings ***
 Documentation       Verify the webpack-built demo
 
-Resource            ../resources/urljsf.resource
-Library             SeleniumLibrary
+Resource            ../resources/xkcd.resource
 
 Suite Setup         Setup Urljsf Suite    00_jsdemo.robot
 Test Setup          Open Page    _static/urljsf/demo/index.html
 Test Teardown       Open Blank
 
-
-*** Variables ***
-${SLIDER_ID}    urljsf-0-url_xkcd
+Test Tags           app:script
 
 
 *** Test Cases ***
-JS Demo Opens
-    [Documentation]    Verify the JS demo opens.
-    Wait Until Element Is Visible    css:${CSS_U_FORM}
-    Capture Element Screenshot    css:${CSS_U_FORM}    00-open.png
-    ${n} =    Verify XKCD Value Changes
-    Capture Element Screenshot    css:${CSS_U_FORM}    01-changed.png
-    Verify XKCD URL    ${n}
-
-
-*** Keywords ***
-Verify XKCD Value Changes
-    [Documentation]    Verify the slider changes.
-    ${old} =    Get XKCD Number
-    Change XKCD
-    ${new} =    Get XKCD Number
-    Should Not Be Equal    ${old}    ${new}
-    RETURN    ${new}
-
-Change XKCD
-    [Documentation]    Change a slider value
-    Press Keys    css:#${SLIDER_ID}    RIGHT    RIGHT
-
-Get XKCD Number
-    [Documentation]    Get a slider value.
-    ${xkcd} =    Get Element Attribute    css:#${SLIDER_ID}    value
-    RETURN    ${xkcd}
-
-Get XKCD URL
-    [Documentation]    Get the submit value.
-    ${url} =    Get Element Attribute    css:${CSS_U_SUBMIT}    href
-    RETURN    ${url}
-
-Verify XKCD URL
-    [Documentation]    Verify the URL against an expected value.
-    [Arguments]    ${n}
-    ${url} =    Get Element Attribute    css:${CSS_U_SUBMIT}    href
-    Should Be Equal As Strings    ${url}    https://xkcd.com/${n}
+JS XKCD Demo Works
+    [Documentation]    Verify the JS demo as built by webpack opens.
+    [Tags]    demo:xkcd
+    Exercise XKCD Demo

atest/suites/01_docs/000_xkcd.robot

@@ -1,16 +1,16 @@
 *** Settings ***
 Documentation       Verify the `xkcd` demo.
 
-Resource            ../../resources/urljsf.resource
-Library             SeleniumLibrary
+Resource            ../../resources/xkcd.resource
 
 Suite Setup         Setup Urljsf Suite    01_docs/000_xkcd
-Test Setup          Open Demo    xkcd
+Test Setup          Open Sphinx Demo    xkcd
 Test Teardown       Open Blank
 
+Test Tags           demo:xkcd
+
 
 *** Test Cases ***
 Xkcd Demo Opens
     [Documentation]    Verify the docs `xkcd` opens.
-    Wait Until Element Is Visible    css:${CSS_U_FORM}
-    Capture Element Screenshot    css:${CSS_U_FORM}    00-open.png
+    Exercise XKCD Demo

atest/suites/01_docs/001_py.robot

@@ -5,9 +5,11 @@ Resource            ../../resources/urljsf.resource
 Library             SeleniumLibrary
 
 Suite Setup         Setup Urljsf Suite    01_docs/001_py
-Test Setup          Open Demo    py
+Test Setup          Open Sphinx Demo    py
 Test Teardown       Open Blank
 
+Test Tags           demo:py
+
 
 *** Test Cases ***
 Py Demo Opens

atest/suites/01_docs/002_installer.robot

@@ -9,9 +9,11 @@ Library             SeleniumLibrary
 Library             urllib.parse
 
 Suite Setup         Setup Urljsf Suite    01_docs/002_installer
-Test Setup          Open Demo    installer
+Test Setup          Open Sphinx Demo    installer
 Test Teardown       Open Blank
 
+Test Tags           demo:installer
+
 
 *** Variables ***
 ${CSS_LICENSE}          ${CSS_U_DATALIST} input[id$="_license"]