From ba8c6064fe2e8b313b0ed3b036035edab998abe7 Mon Sep 17 00:00:00 2001 From: "Zed A. Shaw" Date: Fri, 16 Dec 2022 22:10:14 -0500 Subject: [PATCH] DocsBrowser now works half decent, just need to actually complete the docs on a few samples to work out the more complete look. --- admin/pages/DocsBrowser.svelte | 143 +++++++++++++++++++++++++-------- client/assert.js | 2 +- client/fsm.js | 4 +- commands/codedoc.js | 13 ++- lib/builderator.js | 27 ++++--- lib/ormish.js | 22 ++--- 6 files changed, 151 insertions(+), 60 deletions(-) diff --git a/admin/pages/DocsBrowser.svelte b/admin/pages/DocsBrowser.svelte index 4917c3f..3ea813a 100644 --- a/admin/pages/DocsBrowser.svelte +++ b/admin/pages/DocsBrowser.svelte @@ -4,6 +4,7 @@ import { onMount } from 'svelte'; import Layout from '$/client/Layout.svelte'; import Icon from '$/client/components/Icon.svelte'; + import Markdown from '$/client/components/Markdown.svelte'; import Blockstart from "$/client/components/Blockstart.svelte"; import Code from "$/client/components/Code.svelte"; import api from "$/client/api.js"; @@ -18,6 +19,7 @@ docs_data = status === 200 ? data : {}; url = to_load; + console.log(docs_data); window.scrollTo(0, 0); } @@ -51,54 +53,125 @@ overflow-y: auto; } - #content { + right { + display: flex; + flex-direction: column; min-height: 100vh; height: 100vh; max-height: 100vh; overflow-y: auto; + padding: 0.5rem; + + width: calc(100vw - 300px); + min-width: calc(100vw - 300px); + max-width: calc(100vw - 300px); + } + + export > heading { + display: flex; + flex-direction: column; + background-color: var(--color-bg-secondary); + border: 1px solid var(--value3); + width: 100%; + padding: 0.5rem; + } + + export > heading h4 { + margin: 0px !important; + } + + export > heading meta-data { + display: grid; + gap: 0.5rem; + grid-template-columns: repeat(4, 1fr); + grid-template-rows: auto; + } + + export { + margin-top: 1rem; + } + + export > info { + display: block; + padding: 0.5rem; + } + + export > info commment { + display: block; } - - - -

Docs

 - - {#each Object.keys(index) as item} - {item} - {/each} - - - - - {#if docs_data} - {#each docs_data.exports as exp} -

{ url }

-

{exp.name}

+ +

Docs

 + + {#each Object.keys(index) as item} + {item} + {/each} + + + + +

{ url }

+ {#if docs_data} + {#each docs_data.exports as exp} + {#if exp.isa === "class"} +

Class: { exp.name }

+ {#if exp.comment} - 
-{ exp.comment.value }
-
+ {@html exp.comment} {/if} - {#if exp.isa === "class"} - {#each exp.methods as method} -

{ method.name }

+ + + + {#each exp.methods as member} + + +

{ member.name }

+ + {docs_data.source}:{ member.line_start } + { member.isa } + {#if member.static}static{/if} + {#if member.async}async{/if} + {#if member.generator}generator{/if} + + + {#if exp.comment} - 
-{ exp.comment.value }
-
+ + { @html exp.comment } + {/if} - - {/each} - {:else} - - {/if} +

Signature

+ + + {/each} + {:else} + + +

{exp.name}

+ + {docs_data.source}:{ exp.line_start } + { exp.isa } + {#if exp.static}static{/if} + {#if exp.async}async{/if} + {#if exp.generator}generator{/if} + + + + {#if exp.comment} + + {@html exp.comment} + + {/if} +

Signature

+ + + {/if} - - - + {/each} + {/if} + - diff --git a/client/assert.js b/client/assert.js index 07acd44..2f5ca8f 100644 --- a/client/assert.js +++ b/client/assert.js @@ -2,7 +2,7 @@ import { log } from "./logging.js"; /* I can't believe I have to write this just so I can use the assert that should be standard in every javascript. */ -class AssertionError extends Error { +export class AssertionError extends Error { /* This is from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error * which claims you have to do this weird stuff to make your error actually work. */ diff --git a/client/fsm.js b/client/fsm.js index 8026025..649c944 100644 --- a/client/fsm.js +++ b/client/fsm.js @@ -1,7 +1,7 @@ import assert from "./assert.js"; import { log } from "./logging.js"; -export default class FSM { +export class FSM { constructor(data, events) { // data is really only for logging/debugging @@ -51,3 +51,5 @@ export default class FSM { return this.state; } } + +export default FSM; diff --git a/commands/codedoc.js b/commands/codedoc.js index de51fe0..060b1d0 100644 --- a/commands/codedoc.js +++ b/commands/codedoc.js @@ -3,6 +3,7 @@ import fs from "fs"; import assert from "assert"; import logging from '../lib/logging.js'; import { mkdir, mkdir_to, glob } from "../lib/builderator.js"; +import { create_renderer } from "../lib/docgen.js"; import path from "path"; import template from "lodash/template.js"; import * as acorn from "acorn"; @@ -24,6 +25,15 @@ export const required = [ ["--output ", "Save to file rather than stdout."], ] +const RENDERER = create_renderer(); + +const render_comment = (comment) => { + // strip 1 leading space from the comments, if we strip more it'll + // mess up formatting in markdown for indentation formats + const lines = comment.split(/\n/).map(l => l.replace(/^\s/, '')); + return RENDERER.render(lines.join("\n")); +} + // handy function for checking things are good and aborting const check = (test, fail_message) => { if(!test) { @@ -157,7 +167,7 @@ class ParseWalker { const distance = c.end - line; if(!c.found && distance < 0 && distance > -3) { c.found = true; - return c; + return render_comment(c.value); } } @@ -249,7 +259,6 @@ export const main = async (source_globs, opts) => { const name = normalize_name(fname); - index[name] = result.exports.map(e => { return {isa: e.isa, name: e.name}; }); diff --git a/lib/builderator.js b/lib/builderator.js index a1aca24..0e81081 100644 --- a/lib/builderator.js +++ b/lib/builderator.js @@ -5,8 +5,8 @@ import { log } from "./logging.js"; import Path from "path"; import { execSync } from "child_process"; -/** - * Fixes some common problems with fast-glob on windows. +/* + Fixes some common problems with fast-glob on windows. */ export const glob = (path) => { if(process.platform === "win32") { @@ -36,11 +36,17 @@ export const mkdir = (dir) => { } } -/** - * Given any path to a file, makes sure all its directories are in place. - * - * @param { string } -- path to file - */ +/* + Given any path to a file, makes sure all its directories are in place. + + Example: + + ```javascript + console.log("PRINT"); + ``` + + - `param string` -- path to file + */ export const mkdir_to = (target) => { let dirs = Path.parse(target); mkdir(dirs.dir); @@ -52,9 +58,10 @@ export const write = (target, data) => { fs.writeFileSync(target, data); } -/** Like write but does an OS copy after making the target dir. When given a - * filter it will give the filter function the arguments, let it return contents, - * then write those instead of a copy. +/* + Like write but does an OS copy after making the target dir. When given a + filter it will give the filter function the arguments, let it return contents, + then write those instead of a copy. */ export const copy = (src, dest, filter=null) => { mkdir_to(dest); diff --git a/lib/ormish.js b/lib/ormish.js index 3c5f0cd..d4ce3dd 100644 --- a/lib/ormish.js +++ b/lib/ormish.js @@ -37,17 +37,17 @@ const load_schema = async () => { await load_schema(); -/** - * In some cases (like the generic admin) you need to get validation - * rules but you don't have a specific class to work with. This function - * is called by Model.validation and you can call it directly to get rules - * for a database table. - * - * @param name string - the table name. - * @param rules Object - default rules with empty "" for the rules you want filled in - * @param all boolean - set this to true if you want everything - * @param no_id boolean - defaults to true, set false if you also want the id - * @return Object - the resulting rules to use with Validator +/* + In some cases (like the generic admin) you need to get validation + rules but you don't have a specific class to work with. This function + is called by Model.validation and you can call it directly to get rules + for a database table. + + + `name string` - the table name. + + `rules Object` - default rules with empty "" for the rules you want filled in + + `all boolean` - set this to true if you want everything + + `no_id boolean` - defaults to true, set false if you also want the id + + `return Object` - the resulting rules to use with Validator */ export const validation = (name, rules, all=false, no_id=true) => { assert(rules, "rules parameter is required and will be modified");