mirror of
https://github.com/narrrl/narl-workspace.git
synced 2026-11-03 16:41:27 +01:00
docs: a guide, a wiki and screenshots
The README grew a section per feature and is a good reference, but nothing said where to begin. docs/wiki now has a getting-started page, a guide that walks through one day with the workspace and explains each part where it comes up, and a page per part of the app, each with screenshots of what it describes. Three pages are read out of the code rather than written, so they cannot drift from it: the keys and commands from Help.svelte and commands.ts, the same lists `:help` draws; the settings from .env.example, which gains a heading for the vault, trash and history settings so they no longer sit under mail; and the API from the README's table. `make wiki` writes them, and `--check` fails when one is stale or a link between pages leads nowhere. `--publish` lays the pages out for a GitHub wiki: links without `.md`, images beside them, `[[` escaped so the wiki does not take a command's help text for a link to a page. The screenshots are taken by `make screenshots`: the debug binary on a temporary data directory, with a password made up for the run, filled with an example workspace over the API, and a headless Chromium driven over the DevTools protocol through the views the docs show. Nothing outside the temporary directory is touched but docs/images, and the pictures are cut to 256 colours, a third of their size, which a dark UI does not show. The README opens with the banner, a CI badge, the guide, the features grouped by what they are for, and six of the screenshots.
This commit is contained in:
nvrl committed
1 parent
7b2fd5579c
commit
4eb663e2d7
41 files changed
+2523
-25
No files matched your search
+274
@@ -0,0 +1,274 @@
|
||||
/*
|
||||
* The wiki, from the files it describes: `make wiki`.
|
||||
*
|
||||
* docs/wiki holds the pages. Three of them are not written by hand but read
|
||||
* out of the code, so they cannot drift from it:
|
||||
*
|
||||
* - Commands.md, from the keys in Help.svelte and the commands in commands.ts,
|
||||
* the same lists `:help` draws;
|
||||
* - Configuration.md, from the comments and values in .env.example;
|
||||
* - API.md, from the API section of README.md.
|
||||
*
|
||||
* `bun scripts/wiki.ts` writes those three and checks that every link between
|
||||
* pages and every image resolves. `--publish <dir>` also lays the wiki out for
|
||||
* GitHub: links without `.md`, images beside the pages, a footer saying where
|
||||
* the pages come from. CI does that on every push to main and pushes the result
|
||||
* to the wiki repository; `--check` fails when a generated page is stale.
|
||||
*/
|
||||
import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
|
||||
import { join, resolve } from 'node:path'
|
||||
|
||||
const root = resolve(import.meta.dir, '..')
|
||||
const pages = join(root, 'docs/wiki')
|
||||
const images = join(root, 'docs/images')
|
||||
const repo = process.env.GITHUB_REPOSITORY ?? 'narrrl/narl-workspace'
|
||||
const read = (path: string) => readFileSync(join(root, path), 'utf8')
|
||||
|
||||
const args = process.argv.slice(2)
|
||||
const check = args.includes('--check')
|
||||
const publish = args.includes('--publish') ? args[args.indexOf('--publish') + 1] : undefined
|
||||
if (args.includes('--publish') && !publish) throw new Error('--publish needs a directory')
|
||||
|
||||
const generated = (source: string) =>
|
||||
`<!-- Generated by scripts/wiki.ts from ${source}. Edit that, then run \`make wiki\`. -->\n\n`
|
||||
|
||||
/** A JS string literal's value: `'it\'s'` or `"it's"`. */
|
||||
function unquote(literal: string): string {
|
||||
return literal.slice(1, -1).replace(/\\(.)/g, '$1')
|
||||
}
|
||||
const STRING = `('(?:[^'\\\\]|\\\\.)*'|"(?:[^"\\\\]|\\\\.)*")`
|
||||
|
||||
/** `|` inside a table cell would end it, and a GitHub wiki reads `[[x]]` as a link to page x. */
|
||||
const cell = (text: string) => text.replace(/\|/g, '\\|').replace(/\[\[/g, '\\[\\[')
|
||||
/** A key or command as code, safe in a table even when it holds a backtick. */
|
||||
const code = (text: string) => (text.includes('`') ? `<code>${cell(text).replace(/</g, '<')}</code>` : `\`${cell(text)}\``)
|
||||
|
||||
// --- Commands.md ---------------------------------------------------------------
|
||||
|
||||
function keyTable(source: string, name: string): string {
|
||||
const start = source.indexOf(`const ${name}: [string, string][] = [`)
|
||||
if (start < 0) throw new Error(`Help.svelte has no ${name}`)
|
||||
const body = source.slice(start, source.indexOf('\n ]', start))
|
||||
const pairs = [...body.matchAll(new RegExp(`\\[${STRING}, ${STRING}\\]`, 'g'))].map(([, key, description]) => [unquote(key), unquote(description)])
|
||||
if (pairs.length === 0) throw new Error(`Help.svelte: ${name} is empty`)
|
||||
// `rule` is not a key but the sentence the help column starts with.
|
||||
const rule = pairs.find(([key]) => key === 'rule')
|
||||
const rows = pairs.filter(([key]) => key !== 'rule').map(([key, description]) => `| ${code(key)} | ${cell(description)} |`)
|
||||
const table = ['| key | what it does |', '| --- | --- |', ...rows].join('\n')
|
||||
return rule ? `${rule[1][0].toUpperCase()}${rule[1].slice(1)}.\n\n${table}` : table
|
||||
}
|
||||
|
||||
interface Spec {
|
||||
name: string
|
||||
aliases: string[]
|
||||
args?: string
|
||||
group: string
|
||||
help: string
|
||||
bang?: string
|
||||
}
|
||||
|
||||
function commandSpecs(source: string): Spec[] {
|
||||
const start = source.indexOf('export const commands: CommandSpec[] = [')
|
||||
const end = source.indexOf('\n]\n', start)
|
||||
// Every command is an object literal opened on a line of its own, two in.
|
||||
const blocks = source.slice(start, end).split('\n {\n').slice(1)
|
||||
const field = (block: string, name: string, indent = 4) =>
|
||||
new RegExp(`^${' '.repeat(indent)}${name}: ${STRING},?$`, 'm').exec(block)?.[1]
|
||||
return blocks.map((block) => {
|
||||
const name = field(block, 'name')
|
||||
const group = field(block, 'group')
|
||||
const help = field(block, 'help')
|
||||
if (!name || !group || !help) throw new Error(`commands.ts: a command without a name, group or help:\n${block.slice(0, 200)}`)
|
||||
const aliases = /^ aliases: \[(.*)\],$/m.exec(block)?.[1]
|
||||
const bang = /^ bang: \{/m.test(block) ? field(block, 'help', 6) : undefined
|
||||
const args = field(block, 'args')
|
||||
return {
|
||||
name: unquote(name),
|
||||
group: unquote(group),
|
||||
help: unquote(help),
|
||||
aliases: aliases ? [...aliases.matchAll(new RegExp(STRING, 'g'))].map(([literal]) => unquote(literal)) : [],
|
||||
args: args && unquote(args),
|
||||
bang: bang && unquote(bang),
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
function commandsPage(): string {
|
||||
const help = read('web/src/lib/Help.svelte')
|
||||
const source = read('web/src/lib/commands.ts')
|
||||
const groups = [.../export const groups = \[(.*)\] as const/.exec(source)![1].matchAll(new RegExp(STRING, 'g'))].map(([g]) => unquote(g))
|
||||
const titles = Object.fromEntries(
|
||||
[...help.matchAll(new RegExp(`^ (\\w+): ${STRING},$`, 'gm'))].map(([, group, title]) => [group, unquote(title)]),
|
||||
)
|
||||
const specs = commandSpecs(source)
|
||||
|
||||
const sections = groups.map((group) => {
|
||||
const rows = specs
|
||||
.filter((spec) => spec.group === group)
|
||||
.flatMap((spec) => {
|
||||
const names = [spec.name, ...spec.aliases].map((name) => `:${name}`).join(', ')
|
||||
const usage = spec.args ? `${names} ${spec.args}` : names
|
||||
const row = `| ${code(usage)} | ${cell(spec.help)} |`
|
||||
return spec.bang ? [row, `| ${code(`:${spec.name}!`)} | ${cell(spec.bang)} |`] : [row]
|
||||
})
|
||||
const title = titles[group] ?? group
|
||||
return `### ${title[0].toUpperCase()}${title.slice(1)}\n\n| command | what it does |\n| --- | --- |\n${rows.join('\n')}`
|
||||
})
|
||||
|
||||
return (
|
||||
generated('web/src/lib/Help.svelte and web/src/lib/commands.ts') +
|
||||
`# Keys and commands
|
||||
|
||||
Everything here is also on \`?\` (\`:help\`) inside the app, which draws the same
|
||||
lists. Keys act on whatever has focus: the row under the cursor in the list, or
|
||||
the document in the focused tile. Inside the editor the full vim keymap is live,
|
||||
and \`:\` opens the command line, where \`Tab\` completes commands and their
|
||||
arguments and \`↑\` / \`↓\` recall earlier lines.
|
||||
|
||||
## Keys
|
||||
|
||||
### Browsing and reading
|
||||
|
||||
${keyTable(help, 'keys')}
|
||||
|
||||
### On a board
|
||||
|
||||
${keyTable(help, 'boardKeys')}
|
||||
|
||||
### In the agenda
|
||||
|
||||
${keyTable(help, 'agendaKeys')}
|
||||
|
||||
## Commands
|
||||
|
||||
A command takes a \`!\` for its forcing variant where one exists, the way vim's
|
||||
do: \`:w!\`, \`:space! <name>\`, \`:import!\`.
|
||||
|
||||
${sections.join('\n\n')}
|
||||
`
|
||||
)
|
||||
}
|
||||
|
||||
// --- Configuration.md -------------------------------------------------------------
|
||||
|
||||
function configurationPage(): string {
|
||||
const lines = read('.env.example').split('\n')
|
||||
const out: string[] = []
|
||||
let comment: string[] = []
|
||||
let table: string[] = []
|
||||
const flush = () => {
|
||||
if (table.length) out.push('| setting | example | what it does |', '| --- | --- | --- |', ...table, '')
|
||||
table = []
|
||||
}
|
||||
for (const line of lines) {
|
||||
const section = /^# --- (.+?) -+$/.exec(line)
|
||||
const setting = /^(?:# )?(WORKSPACE_\w+)=(.*)$/.exec(line)
|
||||
if (section) {
|
||||
flush()
|
||||
out.push(`## ${section[1]}`, '')
|
||||
comment = []
|
||||
} else if (setting) {
|
||||
const [, name, value] = setting
|
||||
// A comment above two settings belongs to both: USER and PASSWORD.
|
||||
const text = comment.join(' ').replace(/\s+/g, ' ').trim() || 'See the row above.'
|
||||
const unset = line.startsWith('#') && !/off until/i.test(text) ? ' Unset by default.' : ''
|
||||
table.push(`| \`${name}\` | ${value ? `\`${cell(value)}\`` : ''} | ${cell(text)}${unset} |`)
|
||||
comment = []
|
||||
} else if (line.startsWith('#')) {
|
||||
comment.push(line.replace(/^# ?/, ''))
|
||||
} else if (line.trim() === '') {
|
||||
// A blank line ends a paragraph that belonged to no single setting.
|
||||
if (comment.length && table.length === 0 && out.length) out.push(comment.join(' ').trim(), '')
|
||||
comment = []
|
||||
}
|
||||
}
|
||||
flush()
|
||||
return (
|
||||
generated('.env.example') +
|
||||
`# Configuration
|
||||
|
||||
Every setting is an environment variable, read at start, usually from a \`.env\`
|
||||
file beside the binary (\`cp .env.example .env\`). The older \`DIARY_<NAME>\`
|
||||
spelling of each is still accepted. A value that is set but cannot be read stops
|
||||
the start with the reason rather than falling back to the default.
|
||||
|
||||
## Basics
|
||||
|
||||
${out.join('\n').trim()}
|
||||
`
|
||||
)
|
||||
}
|
||||
|
||||
// --- API.md -----------------------------------------------------------------------
|
||||
|
||||
function apiPage(): string {
|
||||
const readme = read('README.md')
|
||||
const start = readme.indexOf('\n## API\n')
|
||||
const end = readme.indexOf('\n## ', start + 1)
|
||||
if (start < 0) throw new Error('README.md has no API section')
|
||||
return generated('the API section of README.md') + '# API\n' + readme.slice(start + '\n## API\n'.length, end).trimEnd() + '\n'
|
||||
}
|
||||
|
||||
// --- writing, checking, publishing -----------------------------------------------
|
||||
|
||||
const outputs: Record<string, string> = {
|
||||
'Commands.md': commandsPage(),
|
||||
'Configuration.md': configurationPage(),
|
||||
'API.md': apiPage(),
|
||||
}
|
||||
|
||||
let stale = false
|
||||
for (const [name, text] of Object.entries(outputs)) {
|
||||
const path = join(pages, name)
|
||||
const before = existsSync(path) ? readFileSync(path, 'utf8') : ''
|
||||
if (before === text) continue
|
||||
if (check) {
|
||||
console.error(`docs/wiki/${name} is out of date: run \`make wiki\``)
|
||||
stale = true
|
||||
} else {
|
||||
writeFileSync(path, text)
|
||||
console.log(`docs/wiki/${name}`)
|
||||
}
|
||||
}
|
||||
|
||||
const names = readdirSync(pages).filter((name) => name.endsWith('.md'))
|
||||
const broken: string[] = []
|
||||
for (const name of names) {
|
||||
// Code shows links as examples; only the prose around it links.
|
||||
const text = readFileSync(join(pages, name), 'utf8')
|
||||
.replace(/```[\s\S]*?```/g, '')
|
||||
.replace(/`[^`\n]*`/g, '')
|
||||
for (const [, target] of text.matchAll(/\]\(([^)\s]+)\)/g)) {
|
||||
if (/^(https?:|mailto:|#)/.test(target)) continue
|
||||
const path = target.split('#')[0]
|
||||
const exists = path.startsWith('../') ? existsSync(join(pages, path)) : names.includes(path)
|
||||
if (!exists) broken.push(`docs/wiki/${name}: ${target}`)
|
||||
}
|
||||
}
|
||||
if (broken.length) {
|
||||
console.error(`links that lead nowhere:\n ${broken.join('\n ')}`)
|
||||
process.exit(1)
|
||||
}
|
||||
if (stale) process.exit(1)
|
||||
|
||||
if (publish) {
|
||||
const dir = resolve(publish)
|
||||
// Everything but the wiki's own git directory is ours to replace.
|
||||
if (existsSync(dir)) {
|
||||
for (const entry of readdirSync(dir)) if (entry !== '.git') rmSync(join(dir, entry), { recursive: true })
|
||||
}
|
||||
mkdirSync(dir, { recursive: true })
|
||||
cpSync(images, join(dir, 'images'), { recursive: true })
|
||||
for (const name of names) {
|
||||
const text = readFileSync(join(pages, name), 'utf8')
|
||||
.replace(/\]\(\.\.\/images\//g, '](images/')
|
||||
.replace(/\]\(\.\.\/\.\.\/([^)]+)\)/g, `](https://github.com/${repo}/blob/main/$1)`)
|
||||
.replace(/\]\(([\w-]+)\.md(#[^)]*)?\)/g, (_, page, anchor = '') => `](${page}${anchor})`)
|
||||
writeFileSync(join(dir, name), text)
|
||||
}
|
||||
writeFileSync(
|
||||
join(dir, '_Footer.md'),
|
||||
`Written in [\`docs/wiki\`](https://github.com/${repo}/tree/main/docs/wiki) and published by CI on every push to main; an edit made here is overwritten by the next one.\n`,
|
||||
)
|
||||
console.log(`wiki laid out in ${dir}`)
|
||||
}
|
||||
Reference in new issue
Block a user