mirror of
https://github.com/fluffos/fluffos
synced 2026-08-12 18:26:06 -04:00
ca0119d39a
Follow-up to #1270 (the LPC formatter and testsuite reformat). Adds two hand-authored pages to the LPC Language docs tree, wired into sidebars.ts and lpc/index.md (zh-CN sidebar keys rescaffolded, new labels translated): - docs/lpc/style-guide.md -- the LPC house style. Grounded in the Google C++ Style Guide (the base of the driver's own src/.clang-format) and MaJerle's community C style guide, adapted where LPC differs, with conventions measured from the testsuite corpus. Split into the formatter-enforced layout layer (indent, 100-column limit, K&R braces, the full spacing table, case labels, follow-the-source line breaks) and the judgment layer (naming, visibility, comments, preprocessor and error-handling practice). - docs/lpc/formatter.md -- user-facing formatter reference: running it (testsuite/format.sh, bin/format-corpus.mjs on arbitrary file sets, the formatLPC() API, VS Code settings), options and why their defaults mirror src/.clang-format, the normalize-vs-preserve contract, the three write gates (token-sequence equivalence, literal byte-identity, idempotency), the known unbracketed-continuation limitation, and the relation to the C++ style. Verifying the formatter against every rule the docs state surfaced one real discrepancy, fixed here: the empty-for-clause spacing rule was spacing the FULLY-empty header (`for (; ; )`). The pristine corpus and clang-format both write that form tight; partially-empty headers keep their spaced empty clauses. `for (;;)` now renders tight while `for (i = 0; ; i++)` and `for (x = 1; ; )` are unchanged (tight only when everything back to the opening '(' is semicolons). No corpus file changes shape (the corpus's only `for(;;)` sits inside a comment). test.mjs gains a "docs contract" battery: 27 fixed-point spellings taken verbatim from the style guide plus the normalization cases, so a formatter change that breaks a documented rule -- or a doc edit that misstates the formatter -- fails the suite. vscode/lib/format.mjs is the regenerated copy. Validated: node tools/lpc-syntax/test.mjs green (172 checks), testsuite/format.sh --check clean on the current corpus, corpus-wide token/literal/idempotency and width-sweep harnesses clean, and a full two-locale Docusaurus build with no broken links. Claude-Session: https://claude.ai/code/session_01HSL1G3iHXu1dd8XhnBQ2fe Co-authored-by: Claude <noreply@anthropic.com>
97 lines
3 KiB
TypeScript
97 lines
3 KiB
TypeScript
import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
|
|
import generated from './sidebars.generated.json';
|
|
|
|
// The reference trees (efun/, apply/, stdlib/, concepts/, driver/, cli/,
|
|
// zh-CN/) are generated into sidebars.generated.json by gen_sidebar.py,
|
|
// driven by the curated labels/descriptions in sidebar_meta.json.
|
|
// Run `./gen_sidebar.py` after adding, removing, or moving pages in those
|
|
// trees; CI verifies freshness with `./gen_sidebar.py --check`.
|
|
//
|
|
// The lpc/ tree and the top-level pages below are hand-authored.
|
|
const gen = generated as Record<string, any>;
|
|
|
|
const sidebars: SidebarsConfig = {
|
|
docs: [
|
|
{
|
|
type: 'category',
|
|
label: 'Getting Started',
|
|
collapsed: false,
|
|
items: [
|
|
{ type: 'doc', id: 'index', label: 'Overview' },
|
|
{ type: 'doc', id: 'build', label: 'Build from Source' },
|
|
{ type: 'doc', id: 'build-wasm', label: 'Build for WebAssembly' },
|
|
{ type: 'doc', id: 'bug', label: 'Reporting Bugs' },
|
|
],
|
|
},
|
|
{
|
|
type: 'category',
|
|
label: 'LPC Language',
|
|
link: { type: 'doc', id: 'lpc/index' },
|
|
items: [
|
|
{ type: 'doc', id: 'lpc/source-files', label: 'Source Files & Object Names' },
|
|
{ type: 'doc', id: 'lpc/diagnostics', label: 'Compiler Diagnostics' },
|
|
{ type: 'doc', id: 'lpc/style-guide', label: 'Style Guide' },
|
|
{ type: 'doc', id: 'lpc/formatter', label: 'Formatter' },
|
|
{
|
|
type: 'category',
|
|
label: 'Types',
|
|
link: { type: 'doc', id: 'lpc/types/index' },
|
|
items: [
|
|
'lpc/types/general',
|
|
'lpc/types/array',
|
|
'lpc/types/buffer',
|
|
'lpc/types/classes',
|
|
'lpc/types/float',
|
|
'lpc/types/function',
|
|
'lpc/types/mappings',
|
|
'lpc/types/strings',
|
|
'lpc/types/substructures',
|
|
],
|
|
},
|
|
{
|
|
type: 'category',
|
|
label: 'Constructs',
|
|
link: { type: 'doc', id: 'lpc/constructs/index' },
|
|
items: [
|
|
'lpc/constructs/for',
|
|
'lpc/constructs/function',
|
|
'lpc/constructs/if',
|
|
'lpc/constructs/include',
|
|
'lpc/constructs/inherit',
|
|
'lpc/constructs/prototypes',
|
|
'lpc/constructs/ref',
|
|
'lpc/constructs/switch',
|
|
'lpc/constructs/text_blocks',
|
|
'lpc/constructs/while',
|
|
],
|
|
},
|
|
{
|
|
type: 'category',
|
|
label: 'Preprocessor',
|
|
link: { type: 'doc', id: 'lpc/preprocessor/index' },
|
|
items: [
|
|
'lpc/preprocessor/define',
|
|
'lpc/preprocessor/include',
|
|
'lpc/preprocessor/conditionals',
|
|
'lpc/preprocessor/pragma',
|
|
],
|
|
},
|
|
],
|
|
},
|
|
gen['efun'],
|
|
gen['apply'],
|
|
gen['stdlib'],
|
|
gen['concepts'],
|
|
gen['driver'],
|
|
gen['cli'],
|
|
{
|
|
type: 'category',
|
|
label: 'Historical',
|
|
items: [
|
|
{ type: 'doc', id: 'build_v2017', label: 'Build (v2017, legacy)' },
|
|
],
|
|
},
|
|
],
|
|
};
|
|
|
|
export default sidebars;
|