embed chisel documentation front-end application

craigahobbs · Sep 23, 2024 · a78f126 · a78f126
1 parent 7c7efa0
commit a78f126
Show file tree

Hide file tree

Showing 10 changed files with 188 additions and 165 deletions.
diff --git a/Makefile b/Makefile
@@ -40,31 +40,30 @@ doc:
 
     # Dump the documentation example
 	mkdir -p build/doc/html/example
+	cp src/chisel/static/index.html build/doc/html/example/
+	cp src/chisel/static/chiselDoc.bare build/doc/html/example/
 	$(DEFAULT_VENV_PYTHON) -c "$$DUMP_EXAMPLE_PY"
 
 
 .PHONY: test-doc
 commit: test-doc
 test-doc: $(DEFAULT_VENV_BUILD)
-	$(DEFAULT_VENV_BIN)/bare -s static/doc/*.mds static/doc/test/*.mds
-	$(DEFAULT_VENV_BIN)/bare -c 'include <markdownUp.bare>' static/doc/test/runTests.mds$(if $(DEBUG), -d)$(if $(TEST), -v vTest "'$(TEST)'")
+	$(DEFAULT_VENV_BIN)/bare -s src/chisel/static/*.bare src/chisel/static/test/*.bare
+	$(DEFAULT_VENV_BIN)/bare -c 'include <markdownUp.bare>' src/chisel/static/test/runTests.bare$(if $(DEBUG), -d)$(if $(TEST), -v vTest "'$(TEST)'")
 
 
 # Python to dump documentation API responses
 define DUMP_EXAMPLE_PY
 import chisel
-from chisel.doc import CHISEL_DOC_HTML
 import json
 
 app = chisel.Application()
 app.pretty_output = True
 app.add_requests(chisel.create_doc_requests())
-_, _, response = app.request('GET', '/doc/doc_request', query_string=f'name=chisel_doc_request')
-with open(f'build/doc/html/example/index.html', 'wb') as request_file:
-    request_file.write(CHISEL_DOC_HTML)
-with open(f'build/doc/html/example/doc_request', 'wb') as request_file:
+_, _, response = app.request('GET', '/doc/doc_request', query_string='name=chisel_doc_request')
+with open('build/doc/html/example/doc_request', 'wb') as request_file:
     request_file.write(response)
-with open(f'build/doc/html/example/doc_index', 'w') as index_file:
+with open('build/doc/html/example/doc_index', 'w') as index_file:
     json.dump({'title': 'Chisel Documentation Example', 'groups': {'Documentation': ['chisel_doc_request']}}, index_file, indent=2)
 endef
 export DUMP_EXAMPLE_PY
diff --git a/setup.cfg b/setup.cfg
@@ -29,3 +29,8 @@ package_dir =
     = src
 install_requires=
     schema-markdown >= 1.2.0
+
+[options.package_data]
+chisel =
+    static/*.bare
+    static/*.html
diff --git a/src/chisel/doc.py b/src/chisel/doc.py
@@ -5,69 +5,15 @@
 Chisel documentation application
 """
 
+import importlib.resources
+
 from schema_markdown import get_referenced_types
 from schema_markdown.type_model import TYPE_MODEL
 
 from .action import Action, ActionError
 from .request import RedirectRequest, StaticRequest
 
 
-# The chisel-doc application's HTML stub
-CHISEL_DOC_HTML = b'''\
-<!DOCTYPE html>
-<html lang="en">
-    <head>
-        <title>Chisel Documentation Application</title>
-        <meta charset="UTF-8">
-        <meta name="description" content="Chisel Documentation Application">
-        <meta name="viewport" content="width=device-width, initial-scale=1">
-        <link rel="stylesheet" href="https://craigahobbs.github.io/markdown-up/app.css">
-
-        <!-- Preloads -->
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/data.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/library.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/model.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/options.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/parser.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/runtime.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/runtimeAsync.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/value.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/element-model/lib/elementModel.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/app.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/dataTable.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/dataUtil.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/lineChart.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/script.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/scriptLibrary.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/markdown-model/lib/elements.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/markdown-model/lib/parser.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown-doc/lib/schemaMarkdownDoc.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown/lib/encode.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown/lib/parser.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown/lib/schema.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown/lib/schemaUtil.js" as="script">
-        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown/lib/typeModel.js" as="script">
-        <link rel="preload" href="https://craigahobbs.github.io/markdown-up/app.css" as="style">
-        <link rel="preload" href="https://craigahobbs.github.io/markdown-up/markdown-model/static/markdown-model.css" as="style">
-    </head>
-    <body>
-    </body>
-    <script type="module">
-        import {MarkdownUp} from 'https://craigahobbs.github.io/markdown-up/lib/app.js';
-        const app = new MarkdownUp(window, {
-            'markdownText': `\
-~~~ markdown-script
-include 'https://craigahobbs.github.io/chisel/doc/app.mds'
-
-chiselDoc()
-~~~
-`});
-        app.run();
-    </script>
-</html>
-'''
-
-
 def create_doc_requests(requests=None, root_path='/doc', api=True, app=True):
     """
     Yield a series of requests for use with :meth:`~chisel.Application.add_requests` comprising the Chisel
@@ -86,13 +32,25 @@ def create_doc_requests(requests=None, root_path='/doc', api=True, app=True):
         yield DocIndex(requests=requests, urls=(('GET', root_path + '/doc_index'),))
         yield DocRequest(requests=requests, urls=(('GET', root_path + '/doc_request'),))
     if app:
-        yield RedirectRequest((('GET', root_path),), root_path + '/', doc_group='Documentation')
-        yield StaticRequest(
-            'chisel_doc',
-            CHISEL_DOC_HTML,
-            urls=(('GET', root_path + '/'), ('GET', root_path + '/index.html')),
-            doc_group='Documentation'
-        )
+        yield RedirectRequest((('GET', root_path),), root_path + '/', name='chisel_doc_redirect', doc_group='Documentation')
+        with importlib.resources.files('chisel.static').joinpath('index.html').open('rb') as fh:
+            yield StaticRequest(
+                'chisel_doc',
+                fh.read(),
+                'text/html; charset=utf-8',
+                (('GET', root_path + '/'), ('GET', root_path + '/index.html')),
+                'The Chisel documentation HTML',
+                'Documentation'
+            )
+        with importlib.resources.files('chisel.static').joinpath('chiselDoc.bare').open('rb') as fh:
+            yield StaticRequest(
+                'chisel_doc_app',
+                fh.read(),
+                'text/plain; charset=utf-8',
+                (('GET', root_path + '/chiselDoc.bare'),),
+                'The Chisel documentation application',
+                'Documentation'
+            )
 
 
 class DocIndex(Action):

diff --git a/src/chisel/static/chiselDoc.bare b/src/chisel/static/chiselDoc.bare
@@ -0,0 +1,87 @@
+# Licensed under the MIT License
+# https://github.com/craigahobbs/chisel/blob/main/LICENSE
+
+include <args.mds>
+
+
+# The Chisel documentation application main entry point
+async function chiselDoc():
+    args = argsParse(chiselDocArguments)
+    name = objectGet(args, 'name')
+    if name != null:
+        chiselDocRequestPage(name)
+    else:
+        chiselDocIndexPage()
+    endif
+endfunction
+
+
+# The Chisel documentation application arguments
+chiselDocArguments = argsValidate(arrayNew( \
+    objectNew('name', 'name') \
+))
+
+
+# Render the Chisel documentation application index page
+async function chiselDocIndexPage():
+    # Fetch the documentation index API
+    indexURL = 'doc_index'
+    docIndexJSON = systemFetch(indexURL)
+    docIndex = if(docIndexJSON != null, jsonParse(docIndexJSON))
+    if docIndex == null:
+        markdownPrint('**Error:** Failed to fetch chisel index API "' + indexURL + '"')
+        return
+    endif
+    title = objectGet(docIndex, 'title')
+    groups = objectGet(docIndex, 'groups')
+
+    # Render the index page
+    documentSetTitle(title)
+    markdownPrint('# ' + markdownEscape(title))
+    for groupName in arraySort(objectKeys(groups)):
+        markdownPrint('', '## ' + markdownEscape(groupName))
+        for requestName in arraySort(objectGet(groups, groupName)):
+            markdownPrint('', argsLink(chiselDocArguments, requestName, objectNew('name', requestName)))
+        endfor
+    endfor
+endfunction
+
+
+# Render the Chisel documentation application request page
+async function chiselDocRequestPage(typeName):
+    # Fetch the request API
+    requestURL = 'doc_request?name=' + urlEncodeComponent(typeName)
+    docRequestJSON = systemFetch(requestURL)
+    docRequest = if(docRequestJSON != null, jsonParse(docRequestJSON))
+    if docRequest == null:
+        markdownPrint('**Error:** Failed to fetch chisel request API "' + requestURL + '"')
+        return
+    endif
+    doc = objectGet(docRequest, 'doc')
+    urls = objectGet(docRequest, 'urls')
+    types = objectGet(docRequest, 'types')
+
+    # Render the request page
+    documentSetTitle(typeName)
+    markdownPrint(argsLink(chiselDocArguments, 'Index', objectNew('name', null)))
+
+    # Action request?
+    if types != null:
+        elementModelRender(schemaElements(types, typeName, urls))
+        return
+    endif
+
+    # Non-action request
+    markdownPrint('', '# ' + markdownEscape(typeName))
+    if doc != null:
+        markdownPrint('', doc)
+    endif
+    if urls != null && arrayLength(urls) > 0:
+        markdownPrint('', '**Note:** The request is exposed at the following ' + if(arrayLength(urls) == 1, 'URL:', 'URLs:'))
+        for requestURL in urls:
+            method = objectGet(requestURL, 'method', '')
+            path = objectGet(requestURL, 'path')
+            markdownPrint('', '&nbsp;&nbsp;[' + markdownEscape(method) + ' ' + markdownEscape(path) + '](' + path + ')')
+        endfor
+    endif
+endfunction
diff --git a/src/chisel/static/index.html b/src/chisel/static/index.html
@@ -0,0 +1,51 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <title>Chisel Documentation Application</title>
+        <meta charset="UTF-8">
+        <meta name="description" content="Chisel Documentation Application">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <link rel="stylesheet" href="https://craigahobbs.github.io/markdown-up/app.css">
+
+        <!-- Preloads -->
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/data.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/library.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/model.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/options.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/parser.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/runtime.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/runtimeAsync.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/bare-script/lib/value.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/element-model/lib/elementModel.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/app.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/dataTable.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/dataUtil.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/lineChart.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/script.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/lib/scriptLibrary.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/markdown-model/lib/elements.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/markdown-model/lib/parser.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown-doc/lib/schemaMarkdownDoc.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown/lib/encode.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown/lib/parser.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown/lib/schema.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown/lib/schemaUtil.js" as="script">
+        <link rel="modulepreload" href="https://craigahobbs.github.io/markdown-up/schema-markdown/lib/typeModel.js" as="script">
+        <link rel="preload" href="https://craigahobbs.github.io/markdown-up/app.css" as="style">
+        <link rel="preload" href="https://craigahobbs.github.io/markdown-up/markdown-model/static/markdown-model.css" as="style">
+    </head>
+    <body>
+    </body>
+    <script type="module">
+        import {MarkdownUp} from 'https://craigahobbs.github.io/markdown-up/lib/app.js';
+        const app = new MarkdownUp(window, {
+            'markdownText': `\
+~~~ markdown-script
+include 'chiselDoc.bare'
+
+chiselDoc()
+~~~
+`});
+        app.run();
+    </script>
+</html>
diff --git a/static/doc/test/index.html → src/chisel/static/test/index.html b/static/doc/test/index.html → src/chisel/static/test/index.html
@@ -42,7 +42,7 @@
 # Chisel Documentation Tests
 
 ~~~ markdown-script
-include 'runTests.mds'
+include 'runTests.bare'
 ~~~
 `});
         app.run();

diff --git a/static/doc/test/runTests.mds → src/chisel/static/test/runTests.bare b/static/doc/test/runTests.mds → src/chisel/static/test/runTests.bare
@@ -5,7 +5,7 @@ include <unittest.mds>
 include <unittestMock.mds>
 
 # Test includes
-include 'testApp.mds'
+include 'testChiselDoc.bare'
 
 # Test report
 return unittestReport()
diff --git a/static/doc/test/testApp.mds → src/chisel/static/test/testChiselDoc.bare b/static/doc/test/testApp.mds → src/chisel/static/test/testChiselDoc.bare
@@ -1,7 +1,7 @@
 # Licensed under the MIT License
 # https://github.com/craigahobbs/chisel/blob/main/LICENSE
 
-include '../app.mds'
+include '../chiselDoc.bare'
 
 
 async function testChiselDoc_index():

diff --git a/src/tests/test_doc.py b/src/tests/test_doc.py
@@ -30,12 +30,16 @@ def test_default(self):
                     'urls': (('GET', '/doc/doc_request'),)
                 },
                 {
-                    'name': 'redirect_doc',
+                    'name': 'chisel_doc_redirect',
                     'urls': (('GET', '/doc'),)
                 },
                 {
                     'name': 'chisel_doc',
                     'urls': (('GET', '/doc/'), ('GET', '/doc/index.html'))
+                },
+                {
+                    'name': 'chisel_doc_app',
+                    'urls': (('GET', '/doc/chiselDoc.bare'),)
                 }
             ]
         )
@@ -51,12 +55,16 @@ def test_no_request_api(self):
             ],
             [
                 {
-                    'name': 'redirect_doc',
+                    'name': 'chisel_doc_redirect',
                     'urls': (('GET', '/doc'),)
                 },
                 {
                     'name': 'chisel_doc',
                     'urls': (('GET', '/doc/'), ('GET', '/doc/index.html'))
+                },
+                {
+                    'name': 'chisel_doc_app',
+                    'urls': (('GET', '/doc/chiselDoc.bare'),)
                 }
             ]
         )
@@ -108,9 +116,10 @@ def test_doc_index(self):
             'groups': {
                 'Documentation': [
                     'chisel_doc',
+                    'chisel_doc_app',
                     'chisel_doc_index',
-                    'chisel_doc_request',
-                    'redirect_doc'
+                    'chisel_doc_redirect',
+                    'chisel_doc_request'
                 ]
             }
         })