Skip to content

docs: curate the HexDocs module sidebar for 1.0#378

Open
davydog187 wants to merge 1 commit into
mainfrom
docs/curate-hexdocs-1.0
Open

docs: curate the HexDocs module sidebar for 1.0#378
davydog187 wants to merge 1 commit into
mainfrom
docs/curate-hexdocs-1.0

Conversation

@davydog187

Copy link
Copy Markdown
Contributor

Why

Going into 1.0, the HexDocs sidebar rendered ~90 module pages flat and alphabetical — the entire Lua.AST.* node tree, VM/compiler/parser/lexer internals, and five internal *Error types easily confused with the two users actually rescue. Root cause: docs: had no groups_for_modules and no module filtering, so every module without @moduledoc false leaked into the sidebar (only 5 of 60 were hidden).

What

Curated the published module surface to the ~8 modules a library user touches, via filter_modules + groups_for_modules:

Group Modules
Core Lua, Lua.API, Lua.Table, Lua.Chunk
Errors Lua.RuntimeException, Lua.CompilerException, Lua.Parser.Error
Mix Tasks mix lua.eval

Internals (Lua.AST.*, Lua.VM.*, Lua.Compiler.*, Lua.Lexer, Lua.Parser, …) are filtered from the published build only — their @moduledoc stays intact for source readers and h Mod in IEx. Nothing is deleted.

Restructured extras into Guides (Working with Lua · Security & Sandboxing · Mix Tasks) and Examples (the six Livebooks), and wired in the previously orphaned guides/mix_tasks.md.

Content fixes:

  • README's Examples section pointed at examples/*.exs files that became Livebooks in 5d0d8fd → repointed at guides/examples/*.livemd; dropped the stale 1.0.0-rc.0 sentence; disambiguated the two sandboxing links.
  • Lua.API: fixed the {: .neutal}.neutral admonition, the deflua example that bound state but referenced lua, and three typos.
  • working-with-lua.livemd: 0.4.01.0.0-rc pin, filled the empty ~LUA cell.
  • sandboxing.md: coroutity and instruction_count typos.

Notable decisions

  • Lua.Parser is treated as internal. Its public @specs return internal AST types (Lua.AST.Chunk, Lexer.token()), so documenting it drags the internals back into the sidebar. The structured-parse feature for tooling authors is represented by the kept, documented Lua.Parser.Error (its moduledoc names parse_structured/1 as the entry point). Also inlined Lua.Parser.Error.position/0 so the public wire type no longer leaks Lua.AST.Meta.
  • ROADMAP.md is not shipped to HexDocs. It's an internal strategy doc (plan IDs, PR numbers, triage state) and produced broken-link warnings for .agents/plans/ paths. The README's "Coverage and status" already gives users an honest compatibility picture. A purpose-written guides/compatibility.md is an easy follow-up if we want a dedicated page.

Verification

  • mix docszero warnings; sidebar confirmed at the 8 curated modules.
  • mix test — 2523 passed (64 doctests), 7 skipped.
  • mix compile --warnings-as-errors and mix format --check-formatted clean.

No source behavior changes — docs/config only.

The published sidebar rendered ~90 module pages flat — the entire
Lua.AST.* node tree, VM/compiler/parser/lexer internals, and five
internal *Error types easy to confuse with the two users rescue —
because `docs:` had no module grouping or filtering.

Render only the curated public surface (Lua, Lua.API, Lua.Table,
Lua.Chunk, the two public exceptions, Lua.Parser.Error, and the
mix lua.eval task) via `filter_modules`, grouped into Core / Errors /
Mix Tasks. Internal moduledocs stay intact for source readers and
`h Mod` in IEx. Restructure extras into Guides / Examples groups and
wire in the previously orphaned mix_tasks guide.

Lua.Parser is treated as internal: its public specs return internal
AST types, so documenting it drags the internals back in. Keep the
public Lua.Parser.Error (the structured-error type for tooling
authors) and inline its position/0 type so it no longer leaks
Lua.AST.Meta.

Content fixes: repoint the README Examples section at the Livebooks
(the .exs files became .livemd in 5d0d8fd), drop the stale version
sentence, fix the .neutal admonition and the lua/state deflua example
in Lua.API, refresh the working-with-lua Livebook (0.4.0 pin + empty
~LUA cell), and fix typos in the sandboxing guide.

mix docs now builds with zero warnings.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant