port chisel documentation to markdown-script

craigahobbs · May 12, 2022 · 2322939 · 2322939
1 parent 43872f1
commit 2322939
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 25 deletions.
diff --git a/Makefile b/Makefile
@@ -24,26 +24,23 @@ clean:
 # Dump documentation API responses
 define DUMP_DOC_APIS
 import chisel
+from chisel.doc import CHISEL_DOC_HTML
 import json
 
-def dump_doc_request(name):
-    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={name}')
-    with open(f'build/doc/html/{name}/doc_request', 'wb') as request_file:
-        request_file.write(response)
-    with open(f'build/doc/html/{name}/doc_index', 'w') as index_file:
-        json.dump({'title': 'Chisel Documentation Application', 'groups': {'Documentation': [name]}}, index_file, indent=2)
-
-dump_doc_request('chisel_doc_index')
-dump_doc_request('chisel_doc_request')
+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:
+    request_file.write(response)
+with open(f'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_DOC_APIS
 
 doc:
-	mkdir -p build/doc/html/chisel_doc_index build/doc/html/chisel_doc_request
-	cd build/doc/html/chisel_doc_index && $(call WGET_CMD, https://craigahobbs.github.io/chisel-doc/static/index.html)
-	cd build/doc/html/chisel_doc_request && $(call WGET_CMD, https://craigahobbs.github.io/chisel-doc/static/index.html)
+	mkdir -p build/doc/html/example
 	$(DOC_DEFAULT_VENV_CMD)/python3 -c "$$DUMP_DOC_APIS"
diff --git a/README.rst b/README.rst
@@ -94,7 +94,7 @@ requests from
 >>> application.add_requests(chisel.create_doc_requests())
 
 By default the documentation application is hosted at "/doc/". An example of of Chisel's documentation output is
-available `here <https://craigahobbs.github.io/chisel/chisel_doc_request#name=chisel_doc_request>`__.
+available `here <https://craigahobbs.github.io/chisel/example/#var.vName=chisel_doc_request>`__.
 
 
 Development

diff --git a/src/chisel/doc.py b/src/chisel/doc.py
@@ -19,17 +19,80 @@
 <!DOCTYPE html>
 <html lang="en">
     <head>
+        <title>Chisel</title>
         <meta charset="UTF-8">
         <meta name="viewport" content="width=device-width, initial-scale=1">
-        <link rel="stylesheet" href="https://craigahobbs.github.io/chisel-doc/app.css">
-        <link rel="stylesheet" href="https://craigahobbs.github.io/chisel-doc/markdown-model.css">
-        <link rel="stylesheet" href="https://craigahobbs.github.io/chisel-doc/schema-markdown-doc.css">
+        <link rel="stylesheet" href="https://craigahobbs.github.io/markdown-up/markdown-model.css">
+        <link rel="stylesheet" href="https://craigahobbs.github.io/markdown-up/app.css">
     </head>
     <body>
     </body>
     <script type="module">
-        import {ChiselDoc} from 'https://craigahobbs.github.io/chisel-doc/lib/app.js';
-        const app = new ChiselDoc(window);
+        import {MarkdownUp} from 'https://craigahobbs.github.io/markdown-up/lib/app.js';
+        const app = new MarkdownUp(window, {
+            'markdownText': `\
+~~~ markdown-script
+async function indexPage()
+    # Fetch the documentation index API
+    docIndex = fetch('doc_index')
+    title = arrayGet(docIndex, 'title')
+    groups = arrayGet(docIndex, 'groups')
+    groupNames = objectKeys(groups)
+
+    # Render the index page
+    setDocumentTitle(title)
+    markdownPrint('# ' + markdownEncode(title))
+    ixGroup = 0
+    groupLoop:
+        groupName = arrayGet(groupNames, ixGroup)
+        groupRequests = objectGet(groups, groupName)
+        markdownPrint('', '### ' + markdownEncode(groupName))
+        ixRequest = 0
+        requestLoop:
+            requestName = arrayGet(groupRequests, ixRequest)
+            markdownPrint('', '[' + markdownEncode(requestName) + "](#var.vName='" + encodeURIComponent(requestName) + "')")
+            ixRequest = ixRequest + 1
+        jumpif (ixRequest < arrayLength(groupRequests)) requestLoop
+        ixGroup = ixGroup + 1
+    jumpif (ixGroup < arrayLength(groupNames)) groupLoop
+endfunction
+
+async function requestPage(typeName)
+    # Fetch the request API
+    docRequest = fetch('doc_request?name=' + encodeURIComponent(typeName))
+    doc = objectGet(docRequest, 'doc')
+    urls = objectGet(docRequest, 'urls')
+    types = objectGet(docRequest, 'types')
+
+    # Render the request page
+    setDocumentTitle(typeName)
+    markdownPrint('[Index](#var=)')
+
+    # Action request?
+    jumpif (types == null) nonAction
+    schemaPrint(types, typeName, urls)
+    return
+
+    # Non-action request
+    nonAction:
+    markdownPrint('', '# ' + markdownEncode(typeName))
+    if(doc != null, markdownPrint('', doc))
+    jumpif(urls == null || arrayLength(urls) == 0) noURLs
+        markdownPrint('', '**Note:** The request is exposed at the following ' + if(arrayLength(urls) == 1, 'URL:', 'URLs:'))
+        ixURL = 0
+        urlLoop:
+            requestURL = arrayGet(urls, ixURL)
+            method = objectGet(requestURL, 'method')
+            url = objectGet(requestURL, 'url')
+            markdownPrint('', fromCharCode(160, 160) + '[' + markdownEncode(method) + ' ' + markdownEncode(url) + '](' + url + ')')
+            ixURL = ixURL + 1
+        jumpif (ixURL < arrayLength(urls)) urlLoop
+    noURLs:
+endfunction
+
+if(vName != null, requestPage(vName), indexPage())
+~~~
+`});
         app.run();
     </script>
 </html>

diff --git a/src/chisel/request.py b/src/chisel/request.py
@@ -169,7 +169,7 @@ def __init__(self, urls, redirect_url, permanent=True, name=None, doc=None, doc_
         if name is None:
             name = re.sub(r'([^\w]|_)+', '_', f'redirect_{redirect_url}').rstrip('_')
         if doc is None:
-            doc = f'Redirect to {redirect_url}.'
+            doc = f'Redirect to {redirect_url}'
         super().__init__(name=name, urls=urls, doc=doc, doc_group=doc_group)
         self._status = HTTPStatus.MOVED_PERMANENTLY if permanent else HTTPStatus.FOUND
         self._redirect_url = redirect_url

diff --git a/src/tests/test_request.py b/src/tests/test_request.py
@@ -288,7 +288,7 @@ def test_default(self):
         app.add_request(redirect)
 
         self.assertEqual(redirect.name, 'redirect_new')
-        self.assertEqual(redirect.doc, 'Redirect to /new.')
+        self.assertEqual(redirect.doc, 'Redirect to /new')
         status, headers, response = app.request('GET', '/old')
         self.assertEqual(status, '301 Moved Permanently')
         self.assertListEqual(headers, [
@@ -303,7 +303,7 @@ def test_name(self):
         app.add_request(redirect)
 
         self.assertEqual(redirect.name, 'redirect_old_to_new')
-        self.assertEqual(redirect.doc, 'Redirect to /new.')
+        self.assertEqual(redirect.doc, 'Redirect to /new')
         status, headers, response = app.request('GET', '/old')
         self.assertEqual(status, '301 Moved Permanently')
         self.assertListEqual(headers, [
@@ -333,7 +333,7 @@ def test_not_permanent(self):
         app.add_request(redirect)
 
         self.assertEqual(redirect.name, 'redirect_new')
-        self.assertEqual(redirect.doc, 'Redirect to /new.')
+        self.assertEqual(redirect.doc, 'Redirect to /new')
         status, headers, response = app.request('GET', '/old')
         self.assertEqual(status, '302 Found')
         self.assertListEqual(headers, [