DocsBrowser now works half decent, just need to actually complete the docs on a few samples to work out the more complete look.

main
Zed A. Shaw 2 years ago
parent 7463cce5f5
commit ba8c6064fe
  1. 111
      admin/pages/DocsBrowser.svelte
  2. 2
      client/assert.js
  3. 4
      client/fsm.js
  4. 13
      commands/codedoc.js
  5. 25
      lib/builderator.js
  6. 22
      lib/ormish.js

@ -4,6 +4,7 @@
import { onMount } from 'svelte'; import { onMount } from 'svelte';
import Layout from '$/client/Layout.svelte'; import Layout from '$/client/Layout.svelte';
import Icon from '$/client/components/Icon.svelte'; import Icon from '$/client/components/Icon.svelte';
import Markdown from '$/client/components/Markdown.svelte';
import Blockstart from "$/client/components/Blockstart.svelte"; import Blockstart from "$/client/components/Blockstart.svelte";
import Code from "$/client/components/Code.svelte"; import Code from "$/client/components/Code.svelte";
import api from "$/client/api.js"; import api from "$/client/api.js";
@ -18,6 +19,7 @@
docs_data = status === 200 ? data : {}; docs_data = status === 200 ? data : {};
url = to_load; url = to_load;
console.log(docs_data);
window.scrollTo(0, 0); window.scrollTo(0, 0);
} }
@ -51,18 +53,56 @@
overflow-y: auto; overflow-y: auto;
} }
#content { right {
display: flex;
flex-direction: column;
min-height: 100vh; min-height: 100vh;
height: 100vh; height: 100vh;
max-height: 100vh; max-height: 100vh;
overflow-y: auto; 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;
} }
</style> </style>
<Layout footer={ false} header={ false } centered={ true } fullscreen={ true }> <Layout footer={ false} header={ false } centered={ true } fullscreen={ true }>
<Blockstart>
<block class="horizontal">
<sidebar> <sidebar>
<top><h4><a href="/" use:link><Icon name="chevrons-up" /> Docs</a></h4></top> <top><h4><a href="/" use:link><Icon name="chevrons-up" /> Docs</a></h4></top>
<items> <items>
@ -72,33 +112,66 @@
</items> </items>
</sidebar> </sidebar>
<right id="content" style="--pad: 0.5rem;"> <right>
<h1>{ url }</h1>
{#if docs_data} {#if docs_data}
{#each docs_data.exports as exp} {#each docs_data.exports as exp}
<h1>{ url }</h1> {#if exp.isa === "class"}
<h2>{exp.name}</h2> <h2>Class: { exp.name }</h2>
<comment>
{#if exp.comment} {#if exp.comment}
<pre> {@html exp.comment}
{ exp.comment.value }
</pre>
{/if} {/if}
{#if exp.isa === "class"} </comment>
{#each exp.methods as method} <Code content={ exp.code } language="javascript" />
<h4>{ method.name }</h4>
{#each exp.methods as member}
<export>
<heading>
<h4>{ member.name }</h4>
<meta-data>
{docs_data.source}:{ member.line_start }
<em>{ member.isa }</em>
{#if member.static}<b>static</b>{/if}
{#if member.async}<b>async</b>{/if}
{#if member.generator}<b>generator</b>{/if}
</meta-data>
</heading>
<info>
{#if exp.comment} {#if exp.comment}
<pre> <comment>
{ exp.comment.value } { @html exp.comment }
</pre> </comment>
{/if} {/if}
<Code content={ method.code } language="javascript" /> <h4>Signature</h4>
<Code content={ member.code } language="javascript" />
</info>
</export>
{/each} {/each}
{:else} {:else}
<export>
<heading>
<h4> {exp.name}</h4>
<meta-data>
{docs_data.source}:{ exp.line_start }
<em>{ exp.isa }</em>
{#if exp.static}<b>static</b>{/if}
{#if exp.async}<b>async</b>{/if}
{#if exp.generator}<b>generator</b>{/if}
</meta-data>
</heading>
<info>
{#if exp.comment}
<comment>
{@html exp.comment}
</comment>
{/if}
<h4>Signature</h4>
<Code content={ exp.code } language="javascript" /> <Code content={ exp.code } language="javascript" />
</info>
</export>
{/if} {/if}
{/each} {/each}
{/if} {/if}
</right> </right>
</block>
</Blockstart>
</Layout> </Layout>

@ -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. */ /* 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 /* 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. * which claims you have to do this weird stuff to make your error actually work.
*/ */

@ -1,7 +1,7 @@
import assert from "./assert.js"; import assert from "./assert.js";
import { log } from "./logging.js"; import { log } from "./logging.js";
export default class FSM { export class FSM {
constructor(data, events) { constructor(data, events) {
// data is really only for logging/debugging // data is really only for logging/debugging
@ -51,3 +51,5 @@ export default class FSM {
return this.state; return this.state;
} }
} }
export default FSM;

@ -3,6 +3,7 @@ import fs from "fs";
import assert from "assert"; import assert from "assert";
import logging from '../lib/logging.js'; import logging from '../lib/logging.js';
import { mkdir, mkdir_to, glob } from "../lib/builderator.js"; import { mkdir, mkdir_to, glob } from "../lib/builderator.js";
import { create_renderer } from "../lib/docgen.js";
import path from "path"; import path from "path";
import template from "lodash/template.js"; import template from "lodash/template.js";
import * as acorn from "acorn"; import * as acorn from "acorn";
@ -24,6 +25,15 @@ export const required = [
["--output <string>", "Save to file rather than stdout."], ["--output <string>", "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 // handy function for checking things are good and aborting
const check = (test, fail_message) => { const check = (test, fail_message) => {
if(!test) { if(!test) {
@ -157,7 +167,7 @@ class ParseWalker {
const distance = c.end - line; const distance = c.end - line;
if(!c.found && distance < 0 && distance > -3) { if(!c.found && distance < 0 && distance > -3) {
c.found = true; 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); const name = normalize_name(fname);
index[name] = result.exports.map(e => { index[name] = result.exports.map(e => {
return {isa: e.isa, name: e.name}; return {isa: e.isa, name: e.name};
}); });

@ -5,8 +5,8 @@ import { log } from "./logging.js";
import Path from "path"; import Path from "path";
import { execSync } from "child_process"; 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) => { export const glob = (path) => {
if(process.platform === "win32") { if(process.platform === "win32") {
@ -36,10 +36,16 @@ export const mkdir = (dir) => {
} }
} }
/** /*
* Given any path to a file, makes sure all its directories are in place. Given any path to a file, makes sure all its directories are in place.
*
* @param { string } -- path to file Example:
```javascript
console.log("PRINT");
```
- `param string` -- path to file
*/ */
export const mkdir_to = (target) => { export const mkdir_to = (target) => {
let dirs = Path.parse(target); let dirs = Path.parse(target);
@ -52,9 +58,10 @@ export const write = (target, data) => {
fs.writeFileSync(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, Like write but does an OS copy after making the target dir. When given a
* then write those instead of a copy. 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) => { export const copy = (src, dest, filter=null) => {
mkdir_to(dest); mkdir_to(dest);

@ -37,17 +37,17 @@ const load_schema = async () => {
await load_schema(); await load_schema();
/** /*
* In some cases (like the generic admin) you need to get validation 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 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 is called by Model.validation and you can call it directly to get rules
* for a database table. for a database table.
*
* @param name string - the table name. + `name string` - the table name.
* @param rules Object - default rules with empty "" for the rules you want filled in + `rules Object` - default rules with empty "" for the rules you want filled in
* @param all boolean - set this to true if you want everything + `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 + `no_id boolean` - defaults to true, set false if you also want the id
* @return Object - the resulting rules to use with Validator + `return Object` - the resulting rules to use with Validator
*/ */
export const validation = (name, rules, all=false, no_id=true) => { export const validation = (name, rules, all=false, no_id=true) => {
assert(rules, "rules parameter is required and will be modified"); assert(rules, "rules parameter is required and will be modified");

Loading…
Cancel
Save