driver: pages under lib/<pkg>; scope from the findlib naming convention
A package's documentation pages (its mlds, generated landing pages,
assets) now live under lib/<pkg>, mirroring their ids — for most
packages the same directory as its libraries' units, and the id
mirroring is what makes page path references resolve ({!/pkg/dir/page}
is looked up as <-P root>/dir/page-....odoc). The odoc tree reduces to
rendered output: html, indexes, search dbs, occurrences.
The -P/-L scope now comes entirely from findlib plus the naming
convention that an opam package and its findlib libraries share a
toplevel name: a library's owner is its name's first segment, a
package's libraries are the findlib names under its toplevel
(Ocamlfind.sub_libraries), and a dependency's -P root is
lib/<pkg>, gated on its page-index.odoc existing. Renamed packages
(opam's ocamlfind installs findlib's findlib) merely lose page
references into them; module resolution never depended on the
correspondence. With that, nothing needs persisting between driver
runs at all: the partials, their Marshal format and version
discipline, and Voodoo.extra_paths are gone. odd-driver's --odocl-dir
flag goes too (odocls are co-located by construction).
clean_previous distinguishes artifact kinds: module units are swept
from library directories' top level only, pages and assets recursively
under the pages root (another package's units can nest beneath it —
compiler-libs under lib/ocaml), and anything under the package's
output tree, including legacy partials. Index roots are normalised to
directory paths before pruning nested roots — the trailing-slash
mismatch between lib.dir and lib_root/<pkg> otherwise pruned both
copies of the same root, yielding empty search indexes.
odd's reference scan walks installed packages' lib/<pkg> trees for
pages, page roots are documented packages' lib/<pkg> dirs, and
ambiguity suggestions qualify pages by their position under their
package root. The pre-remove hook also prunes the id-mirror
directories it empties.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add 'switchdocs complete' for reference completion
Given a partial reference, list the full references it could become — the
reverse of `show`: resolve the parent context and enumerate its children
matching the final, incomplete component. Built on the shared Refs module.
Forms handled:
- dotted members, with kind tags: `List.m` -> List.map, ...;
`module-List.type-` -> module-List.type-t (Stdlib open, so bare names work)
- path roots: `/o` -> /odoc, /odoc.model, /ocaml-compiler, ...
- units under a root: `/odoc.model/` -> /odoc.model/Odoc_model, ...
- path + dotted: `/odoc.model/Odoc_model.Pa` -> .../Odoc_model.Paths
- bare top-level names: units + open-module members
Output preserves the verbatim stem + kind prefix and appends the matched
name. Input is split with a tolerant scanner (odoc's tokenizer rejects the
empty trailing identifier we need). Wrapped internal modules (names with
`__`) are filtered as hidden. Resolution failures yield no completions, not
errors. See DESIGN_COMPLETE.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
driver: pages under lib/<pkg>; scope from the findlib naming convention
A package's documentation pages (its mlds, generated landing pages,
assets) now live under lib/<pkg>, mirroring their ids — for most
packages the same directory as its libraries' units, and the id
mirroring is what makes page path references resolve ({!/pkg/dir/page}
is looked up as <-P root>/dir/page-....odoc). The odoc tree reduces to
rendered output: html, indexes, search dbs, occurrences.
The -P/-L scope now comes entirely from findlib plus the naming
convention that an opam package and its findlib libraries share a
toplevel name: a library's owner is its name's first segment, a
package's libraries are the findlib names under its toplevel
(Ocamlfind.sub_libraries), and a dependency's -P root is
lib/<pkg>, gated on its page-index.odoc existing. Renamed packages
(opam's ocamlfind installs findlib's findlib) merely lose page
references into them; module resolution never depended on the
correspondence. With that, nothing needs persisting between driver
runs at all: the partials, their Marshal format and version
discipline, and Voodoo.extra_paths are gone. odd-driver's --odocl-dir
flag goes too (odocls are co-located by construction).
clean_previous distinguishes artifact kinds: module units are swept
from library directories' top level only, pages and assets recursively
under the pages root (another package's units can nest beneath it —
compiler-libs under lib/ocaml), and anything under the package's
output tree, including legacy partials. Index roots are normalised to
directory paths before pruning nested roots — the trailing-slash
mismatch between lib.dir and lib_root/<pkg> otherwise pruned both
copies of the same root, yielding empty search indexes.
odd's reference scan walks installed packages' lib/<pkg> trees for
pages, page roots are documented packages' lib/<pkg> dirs, and
ambiguity suggestions qualify pages by their position under their
package root. The pre-remove hook also prunes the id-mirror
directories it empties.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
driver: pages under lib/<pkg>; scope from the findlib naming convention
A package's documentation pages (its mlds, generated landing pages,
assets) now live under lib/<pkg>, mirroring their ids — for most
packages the same directory as its libraries' units, and the id
mirroring is what makes page path references resolve ({!/pkg/dir/page}
is looked up as <-P root>/dir/page-....odoc). The odoc tree reduces to
rendered output: html, indexes, search dbs, occurrences.
The -P/-L scope now comes entirely from findlib plus the naming
convention that an opam package and its findlib libraries share a
toplevel name: a library's owner is its name's first segment, a
package's libraries are the findlib names under its toplevel
(Ocamlfind.sub_libraries), and a dependency's -P root is
lib/<pkg>, gated on its page-index.odoc existing. Renamed packages
(opam's ocamlfind installs findlib's findlib) merely lose page
references into them; module resolution never depended on the
correspondence. With that, nothing needs persisting between driver
runs at all: the partials, their Marshal format and version
discipline, and Voodoo.extra_paths are gone. odd-driver's --odocl-dir
flag goes too (odocls are co-located by construction).
clean_previous distinguishes artifact kinds: module units are swept
from library directories' top level only, pages and assets recursively
under the pages root (another package's units can nest beneath it —
compiler-libs under lib/ocaml), and anything under the package's
output tree, including legacy partials. Index roots are normalised to
directory paths before pruning nested roots — the trailing-slash
mismatch between lib.dir and lib_root/<pkg> otherwise pruned both
copies of the same root, yielding empty search indexes.
odd's reference scan walks installed packages' lib/<pkg> trees for
pages, page roots are documented packages' lib/<pkg> dirs, and
ambiguity suggestions qualify pages by their position under their
package root. The pre-remove hook also prunes the id-mirror
directories it empties.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
driver: pages under lib/<pkg>; scope from the findlib naming convention
A package's documentation pages (its mlds, generated landing pages,
assets) now live under lib/<pkg>, mirroring their ids — for most
packages the same directory as its libraries' units, and the id
mirroring is what makes page path references resolve ({!/pkg/dir/page}
is looked up as <-P root>/dir/page-....odoc). The odoc tree reduces to
rendered output: html, indexes, search dbs, occurrences.
The -P/-L scope now comes entirely from findlib plus the naming
convention that an opam package and its findlib libraries share a
toplevel name: a library's owner is its name's first segment, a
package's libraries are the findlib names under its toplevel
(Ocamlfind.sub_libraries), and a dependency's -P root is
lib/<pkg>, gated on its page-index.odoc existing. Renamed packages
(opam's ocamlfind installs findlib's findlib) merely lose page
references into them; module resolution never depended on the
correspondence. With that, nothing needs persisting between driver
runs at all: the partials, their Marshal format and version
discipline, and Voodoo.extra_paths are gone. odd-driver's --odocl-dir
flag goes too (odocls are co-located by construction).
clean_previous distinguishes artifact kinds: module units are swept
from library directories' top level only, pages and assets recursively
under the pages root (another package's units can nest beneath it —
compiler-libs under lib/ocaml), and anything under the package's
output tree, including legacy partials. Index roots are normalised to
directory paths before pruning nested roots — the trailing-slash
mismatch between lib.dir and lib_root/<pkg> otherwise pruned both
copies of the same root, yielding empty search indexes.
odd's reference scan walks installed packages' lib/<pkg> trees for
pages, page roots are documented packages' lib/<pkg> dirs, and
ambiguity suggestions qualify pages by their position under their
package root. The pre-remove hook also prunes the id-mirror
directories it empties.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
jon.recoil.org