jon.recoil.org / odd
Odoc docs
0
Fork 1

Configure Feed

Select the types of activity you want to include in your feed.

9 2 0

Clone this repository

https://git.vm.fail/jon.recoil.org/odd https://git.vm.fail/did:plc:2osshuqe3djotabmzmyirjxw
ssh://git@knot.ludl.am:2222/jon.recoil.org/odd ssh://git@knot.ludl.am:2222/did:plc:2osshuqe3djotabmzmyirjxw

For self-hosted knots, clone URLs may differ based on your setup.


Download tar.gz Download .zip
README.md

odoc-switchdocs#

Keep an opam switch's HTML documentation continuously up to date.

switchdocs wires opam's post-install-commands, post-remove-commands and post-session-commands hooks so that after every successful opam install / opam upgrade / opam remove, the docs for exactly the packages that changed are regenerated, in dependency order, by odoc_driver_opam. The per-package hooks are plain coreutils (a touch to mark a package stale, an rm -rf to drop a removed one's docs), so they keep working even when switchdocs itself isn't installed in the switch; only the once-per-session worker needs the binary. Docs are written to $OPAM_SWITCH_PREFIX/odoc/<package>/, with a landing page at $OPAM_SWITCH_PREFIX/odoc/index.html. (This is switchdocs' own tree, kept separate from opam's $OPAM_SWITCH_PREFIX/doc, where packages install their own documentation.)

See DESIGN.md for the full design.

Setup#

$ switchdocs setup          # show the opam configuration to be added
$ switchdocs setup --apply  # add it to ~/.opam/config via `opam option`

odoc_driver_opam must be installed in each switch you want documented (it links against the switch's odoc).

Commands#

  • switchdocs sync — session worker (the post-session hook); rebuilds every package marked stale, in dependency order, and regenerates the landing page. Always exits 0; details go to $OPAM_SWITCH_PREFIX/var/cache/switchdocs/log.
  • switchdocs rebuild [--all | PKG...] — mark packages stale and sync. Exits non-zero on failure (user-facing, unlike the hook commands).
  • switchdocs order [PKG...] — print the dependency order that sync would use (debugging aid).
  • switchdocs search [--package PKG]... [-n N] QUERY — search the generated documentation. Queries every package's sherlodoc_db.marshal together (a single query covers the whole switch), printing each match with its owning package. --package restricts to named packages.
  • switchdocs show REFERENCE — print an item's documentation as Markdown, resolving an odoc reference (e.g. Stdlib.List.map, Astring.String, or a package-qualified /stdlib/Stdlib.List.map) against the whole switch.

Development#

$ opam install . --deps-only --with-test
$ dune build
$ dune runtest