docs: curate the HexDocs module sidebar for 1.0#378
Open
davydog187 wants to merge 1 commit into
Open
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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*Errortypes easily confused with the two users actually rescue. Root cause:docs:had nogroups_for_modulesand no module filtering, so every module without@moduledoc falseleaked 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:Lua,Lua.API,Lua.Table,Lua.ChunkLua.RuntimeException,Lua.CompilerException,Lua.Parser.Errormix lua.evalInternals (
Lua.AST.*,Lua.VM.*,Lua.Compiler.*,Lua.Lexer,Lua.Parser, …) are filtered from the published build only — their@moduledocstays intact for source readers andh Modin 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:
examples/*.exsfiles that became Livebooks in5d0d8fd→ repointed atguides/examples/*.livemd; dropped the stale1.0.0-rc.0sentence; disambiguated the two sandboxing links.Lua.API: fixed the{: .neutal}→.neutraladmonition, thedefluaexample that boundstatebut referencedlua, and three typos.working-with-lua.livemd:0.4.0→1.0.0-rcpin, filled the empty~LUAcell.sandboxing.md:coroutityandinstruction_counttypos.Notable decisions
Lua.Parseris 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, documentedLua.Parser.Error(its moduledoc namesparse_structured/1as the entry point). Also inlinedLua.Parser.Error.position/0so the public wire type no longer leaksLua.AST.Meta.ROADMAP.mdis 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-writtenguides/compatibility.mdis an easy follow-up if we want a dedicated page.Verification
mix docs— zero warnings; sidebar confirmed at the 8 curated modules.mix test— 2523 passed (64 doctests), 7 skipped.mix compile --warnings-as-errorsandmix format --check-formattedclean.No source behavior changes — docs/config only.