mirror of
https://github.com/fluffos/fluffos
synced 2026-08-12 18:26:06 -04:00
7 commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Yucong Sun
|
89060c5a6b
|
docs: fully-expandable generated sidebar + Chinese docs via Docusaurus i18n (#1246)
* docs: fully-expandable generated sidebar, replacing index.md link pages
Rework docs navigation so the sidebar expands to every page of every
reference tree, instead of terminating at generated index.md link lists:
- New docs/gen_sidebar.py (replaces gen_index.py + update_index.sh):
walks efun/, apply/, stdlib/, concepts/, driver/, cli/ and zh-CN/ and
emits sidebars.generated.json — a full Docusaurus category tree per
directory. Category landing pages are now `generated-index` card pages
(title/description/slug), so all generated index.md files are deleted.
--check mode verifies freshness; new .github/workflows/docs-sidebar.yml
runs it in CI.
- New docs/sidebar_meta.json holds curated presentation: category labels,
one-line descriptions (shown on the landing cards), explicit ordering
(driver/cli/concepts read top-down from user-facing to internals) and
per-page label overrides.
- sidebars.ts becomes a hand-authored skeleton (Getting Started, lpc/,
Historical) that splices in the generated trees.
Content reorganization (from a docs-wide review):
- Move misplaced efun pages out of efun/general: terminal/protocol efuns
(act_mxp, send_zmp, request_term_*) to interactive/, debugging efuns
(check_memory, dump_*, clear_debug_level, destructed_objects) to
internals/, shallow_inherit_list to system/.
- Delete stub duplicates superseded by complete pages elsewhere:
general/parse_{add_synonym,dump,my_rules,remove}, contrib/{shuffle,
element_of}.
Modernize key pages with MDX:
- index.mdx: landing page with a card grid linking each doc section.
- build.mdx: per-platform <Tabs> (Ubuntu/macOS/Windows/Alpine+Docker),
admonitions, VitePress [[toc]] leftover removed, stale per-platform CI
workflow links updated to the unified ci.yml.
- ffi-plan.md: GitHub-style [!CAUTION] alert converted to an admonition.
`npm run build` passes clean (onBrokenLinks: throw, no warnings).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0174GM2azvAHBmvyESwxm5om
* docs: serve the Chinese corpus through Docusaurus i18n
Move the zh-CN/ directory out of the default docs tree and into a proper
Docusaurus locale (i18n/zh-CN/docusaurus-plugin-content-docs/current/):
- The flat zh-CN/efun/ directory (333 pages) is re-homed to mirror the
categorized English layout (name-matched 1:1; `hash` maps to strings/
per its own frontmatter). apply/ pages map 1:1; the stray English-text
zh-CN/apply/master/view_errors.md documents a MudOS-era apply that no
longer exists in the driver and is dropped; stdlib/db/database_zh.md
becomes the i18n translation of stdlib/db/database.md; the Chinese
build guide becomes the translation of build.mdx.
- Untranslated pages automatically fall back to English content under
/zh-CN/, so the whole site is navigable in either locale from the new
navbar locale dropdown.
- Both locales share one sidebar. Generated sidebar items now carry
stable `key` fields (the directory/doc path) so translation keys are
unique (both efun/ and stdlib/ have an "Arrays" category, crypto and
strings both document `hash`). Category labels, generated-index
titles/descriptions, navbar and footer are translated in
i18n/zh-CN/...; theme UI strings come from Docusaurus' bundled
zh-Hans translations. Translated landing page at /zh-CN/.
- The "中文文档" sidebar section, the zh-CN tree in gen_sidebar.py /
sidebar_meta.json, and its slice of sidebars.generated.json are gone.
- Relative .md-file links on pages that render in both locales break
the localized build (the file->permalink map points at the localized
copy), so concepts/, the two socket_*_option pages and the config.md
generator now emit extension-less route links instead.
- zh interactive.md/objects.md get explicit slugs like their English
counterparts (a doc named after its parent directory is otherwise a
Docusaurus category-index doc, colliding with the generated-index
route).
`npm run build` builds both locales clean (onBrokenLinks: throw).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0174GM2azvAHBmvyESwxm5om
---------
Co-authored-by: Claude <noreply@anthropic.com>
|
||
|
Yucong Sun
|
c914f03d66
|
Add local search and documentation guide for docs site (#1221)
* docs: add local full-text search and a contributor README Add @easyops-cn/docusaurus-search-local to the Docusaurus site so the docs get an offline search bar (index built at build time, no external service). English and zh-CN pages are both indexed, and matched terms are highlighted on the target page. Add docs/README.md describing the Docusaurus setup, local dev/build commands, search behavior, directory layout, and gotchas; exclude it from the published site alongside CLAUDE.md. Point the root README's docs/ entry at it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSzcESzU9947zkGzQ6SMmE * docs: remove dead framework leftovers, fix index generation, complete the nav Delete the VitePress (.vitepress/) and Jekyll (_layouts/, css/) leftovers, the one-shot migration scripts (fix_md_header.py, fix_seealso.py), and the stale keywords.json snapshot; prune the matching .gitignore entries and docusaurus exclude patterns. Rewrite gen_index.py for Docusaurus: it emitted dead .html links and legacy 'layout: doc' frontmatter, choked on non-markdown entries, and dropped nested categories — regenerating an index would have broken it. It now emits the extension-less links the site actually uses, links nested category indexes (restoring apply/* on the zh-CN index), and refuses to run on the docs root. Fix update_index.sh's copy-paste titles (zh-CN efun/build were titled 'APPLY'), stop it clobbering the hand-written lpc/index.md, and cover cli/. Regenerated indexes pick up the missing driver/ffi-plan entry. add_missing_efuns.py now takes the keywords.json path as an argument instead of requiring a stale copy. Move CNAME and the Google site-verification file into static/ so they actually reach the published build output. Complete the sidebar: link the CLI category to cli/index and add the missing portbind/symbol/generate_keywords pages, and expose the previously orphaned stdlib section under Reference. Promote onBrokenLinks to 'throw' now the build is warning-free, and drop the empty Demo section from the landing page. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSzcESzU9947zkGzQ6SMmE * docs: strip legacy 'layout: doc' frontmatter from all pages Mechanical sweep removing the Jekyll-era 'layout: doc' line from every doc page's frontmatter (Docusaurus ignores it), and the matching line from the templates in docs/CLAUDE.md so new pages don't reintroduce it. No content changes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSzcESzU9947zkGzQ6SMmE --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Yucong Sun
|
2063e95436
|
Fix Docusaurus sidebar, broken links, and gh-pages CI (#1209)
* Reorder sidebar: Driver > CLI > Reference (LPC Language, Apply, EFUN, Concepts) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Fix Docusaurus build: broken links, duplicate routes, and gh-pages CI - Strip .html from all markdown link targets (51 files) for Docusaurus URL routing - Add slug: frontmatter to 4 files whose names match their parent directory (interactive.md, objects.md, README.md, build.md) to prevent Docusaurus's category-index convention from creating duplicate routes - Fix one missed .html link in zh-CN/build/index.md - Move onBrokenMarkdownLinks to markdown.hooks (Docusaurus v4 deprecation) - Update gh-pages.yml: rename to Docusaurus, use node 22, correct build path (docs/build instead of docs/.vitepress/dist) Build now completes with [SUCCESS] and zero warnings or broken links. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
gesslar
|
e1a50d2642
|
Generate driver config docs and a starter config from rc.cc tables (#1206)
* Generate driver config docs and a starter config from rc.cc tables Make the runtime-config option tables in rc.cc the single source of truth for documentation, so the docs can no longer drift from the driver. - rc.cc: add `category`/`description` fields to the int-option table (INT_FLAGS) and introduce a STR_FLAGS table for the simple string options, parsing them directly from the table in read_config(). - docs/gen_config_docs.py: generate docs/driver/config.md from those tables (resolving expression/macro defaults). `--check` mode fails if the committed doc is stale. - .github/workflows/config-docs.yml: run the generator with --check on changes to rc.cc/options_internal.h/the generator/the doc. - docs/driver/config.md: regenerated; now covers all recognized options accurately (previously ~half, with some stale/nonexistent entries). - driver --generate-config: emit a complete, bootable starter config to stdout (ints at defaults, required paths as placeholders, websocket/ TLS/external bits commented out). Comment lines are wrapped to stay under the parser's per-line limit. - Config.example: add the 9 previously-missing options and fix the "call_out(0) next level" -> "nest level" typo. - CLAUDE.md / docs/CLAUDE.md / docs/cli/driver.md: document the source of truth, the regeneration workflow, and the new flag. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * Config.example: keep only valid options Remove options the driver doesn't actually use: - obsolete (driver warns to delete): `binary directory`, `swap file` - unrecognized / silently ignored: `apply cache bits`, `maximum users`, `compiler stack size` Relocate `evaluator stack size` (a valid limit) up with the other limits and drop the now-empty "not currently used or implemented" section, and remove the `binary directory` mention from the header note. Verified: the cleaned sample boots a mudlib to "Initializations complete" with no obsolete-line warnings. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|
Yucong Sun
|
ddf8b9740d
|
more doc fixes. (#1137)
* docs: Fix multiple documentation issues
This commit addresses several documentation inconsistencies and gaps
identified by comparing docs with actual code implementations:
**Build Documentation Fixes:**
- Updated macOS build instructions to clarify Homebrew paths for both
Apple Silicon and Intel Macs, emphasizing modern Homebrew defaults
- Added clarity to SQLite version options (=1 vs =2) explaining the
differences and recommending version 2
**CLI Tool Documentation:**
- Added documentation for the `symbol` utility (docs/cli/symbol.md)
- Tool for loading and analyzing LPC files
- Usage: symbol <config> lpc_file
- Added documentation for the `portbind` utility (docs/cli/portbind.md)
- Privilege-separated port binding for FluffOS
- Allows binding to privileged ports then dropping privileges
**Apply Documentation:**
- Added mxp_enable apply (docs/apply/interactive/mxp_enable.md)
- Called when MXP protocol is negotiated with client
- Added mxp_tag apply (docs/apply/interactive/mxp_tag.md)
- Processes MXP tags from client
- Added zmp_command apply (docs/apply/interactive/zmp.md)
- Handles ZMP (Zenith Mud Protocol) commands
- Added receive_ed apply (docs/apply/interactive/receive_ed.md)
- Post-processes ed editor output
- Removed obsolete view_errors.md documentation
- Apply not found in source code, appears to be deprecated
All new documentation follows existing format conventions and includes
cross-references to related efuns and applies where applicable.
* docs: Add missing apply and efun documentation
This commit adds documentation for previously undocumented applies and
efuns, completing the documentation coverage for recent FluffOS features.
**Apply Documentation:**
- terminal_colour_replace (interactive): Custom color token replacement
callback for terminal_colour() efun preprocessing
- parser_error_message (master): Custom error message generation for
parse_sentence() failures
**Efun Documentation:**
- hash() (crypto package): Complete documentation for cryptographic hash
function with support for modern algorithms (SHA-3, BLAKE2, SM3)
- Includes security recommendations and version compatibility notes
- Documents all supported algorithms from legacy (MD5, SHA-1) to modern
(SHA-3, BLAKE2b512)
- Created new crypto package documentation directory
**Index Updates:**
- Updated docs/apply/interactive/index.md with new applies:
mxp_enable, mxp_tag, receive_ed, terminal_colour_replace, zmp
- Updated docs/apply/master/index.md with parser_error_message
- Removed obsolete view_errors reference from master index
- Added crypto section to docs/efun/index.md
These additions address documentation gaps identified by comparing the
source code with existing documentation, particularly for the crypto
package enhancements from commit
|
||
|
Yucong Sun
|
eb6b984f37
|
docs: Fix multiple documentation issues (#1136)
This commit addresses several documentation inconsistencies and gaps identified by comparing docs with actual code implementations: **Build Documentation Fixes:** - Updated macOS build instructions to clarify Homebrew paths for both Apple Silicon and Intel Macs, emphasizing modern Homebrew defaults - Added clarity to SQLite version options (=1 vs =2) explaining the differences and recommending version 2 **CLI Tool Documentation:** - Added documentation for the `symbol` utility (docs/cli/symbol.md) - Tool for loading and analyzing LPC files - Usage: symbol <config> lpc_file - Added documentation for the `portbind` utility (docs/cli/portbind.md) - Privilege-separated port binding for FluffOS - Allows binding to privileged ports then dropping privileges **Apply Documentation:** - Added mxp_enable apply (docs/apply/interactive/mxp_enable.md) - Called when MXP protocol is negotiated with client - Added mxp_tag apply (docs/apply/interactive/mxp_tag.md) - Processes MXP tags from client - Added zmp_command apply (docs/apply/interactive/zmp.md) - Handles ZMP (Zenith Mud Protocol) commands - Added receive_ed apply (docs/apply/interactive/receive_ed.md) - Post-processes ed editor output - Removed obsolete view_errors.md documentation - Apply not found in source code, appears to be deprecated All new documentation follows existing format conventions and includes cross-references to related efuns and applies where applicable. Co-authored-by: Claude <noreply@anthropic.com> |
||
|
Yucong Sun
|
3ec3a92393 | Adding docs for CLI tools |