Deploying to gh-pages from @ c4a4277 🚀

Author: balat

dev/index.md

@@ -0,0 +1,3 @@
+# OCaml Package Documentation
+
+- [wodoc](wodoc/index.md)

dev/llms-full.txt

@@ -0,0 +1,29 @@
+# Wodoc
+
+> *wodoc* (web \+ odoc) is an [odoc](https://github.com/ocaml/odoc) driver that builds complete, styled **websites** from `.mld` and `.mli` sources — not just API documentation.
+
+## Manual
+- [Wodoc](wodoc/index.md)
+- [How wodoc works](wodoc/overview.md)
+- [Directives](wodoc/directives.md)
+- [Authoring: what survives on ocaml.org](wodoc/authoring.md)
+- [Configuration: the `doc/wodoc` file](wodoc/config.md)
+- [Commands](wodoc/commands.md)
+- [Adding a blog](wodoc/blog.md)
+- [API reference](wodoc/api.md)
+- [OCaml Package Documentation](index.md)
+
+## API
+- [Module `Assemble.Parts`](wodoc/Wodoc-Assemble-Parts.md)
+- [Module `Wodoc.Assemble`](wodoc/Wodoc-Assemble.md)
+- [Module `Wodoc.Blog`](wodoc/Wodoc-Blog.md)
+- [Module `Wodoc.Build`](wodoc/Wodoc-Build.md)
+- [Module `Wodoc.Config`](wodoc/Wodoc-Config.md)
+- [Module `Wodoc.Convert`](wodoc/Wodoc-Convert.md)
+- [Module `Wodoc.Llms`](wodoc/Wodoc-Llms.md)
+- [Module `Wodoc.Nav`](wodoc/Wodoc-Nav.md)
+- [Module `Wodoc.Preprocess`](wodoc/Wodoc-Preprocess.md)
+- [Module `Wodoc.Render`](wodoc/Wodoc-Render.md)
+- [Module `Wodoc.Resolve`](wodoc/Wodoc-Resolve.md)
+- [Module `Wodoc.Sexp`](wodoc/Wodoc-Sexp.md)
+- [Module `Wodoc`](wodoc/Wodoc.md)

dev/llms.txt

@@ -0,0 +1,15 @@
+
+# Module `Assemble.Parts`
+
+```ocaml
+type t = {
+  title : string; (* plain text of the page's <h1> *)
+  preamble : string; (* the odoc-preamble header, verbatim *)
+  toc : string; (* the odoc-tocs block, verbatim (may be empty) *)
+  content : string; (* the odoc-content block, verbatim *)
+}
+```
+```ocaml
+val of_odoc_html : string -> t
+```
+Extract the parts from a full odoc-generated HTML page.

dev/wodoc/Wodoc-Assemble-Parts.md

@@ -0,0 +1,57 @@
+
+# Module `Wodoc.Assemble`
+
+Assembly layer: wrap odoc's rendered HTML in a project-provided site template.
+
+wodoc stays generic: the project owns all of its chrome (header, menus, drawer, footer, version selector) as a plain HTML *template* with named holes. This module only:
+
+- extracts the meaningful parts from odoc's HTML output ([`Parts.of_odoc_html`](./Wodoc-Assemble-Parts.md#val-of_odoc_html));
+- fills the holes of the template ([`fill`](./#val-fill));
+- marks the current navigation entry ([`mark_current`](./#val-mark_current)).
+A template is HTML containing holes written `{{name}}`. The standard holes filled by [`page`](./#val-page) are `{{base}}`, `{{title}}`, `{{preamble}}`, `{{toc}}` and `{{content}}`. Menu links carry a `data-wodoc-page` attribute; the entry whose value equals the current page id receives the `current` class.
+
+```ocaml
+module Parts : sig ... end
+```
+```ocaml
+val fill : template:string -> (string * string) list -> string
+```
+`fill ~template bindings` replaces every `{{key}}` in `template` with its bound value. Unbound holes are left untouched.
+
+```ocaml
+val mark_current : 
+  ?attr:string ->
+  ?class_:string ->
+  current:string ->
+  string ->
+  string
+```
+`mark_current ~current html` adds `class_` (default `"current"`) to every start tag whose `attr` (default `"data-wodoc-page"`) equals `current`, merging with an existing `class`. `current = ""` marks nothing.
+
+```ocaml
+val page : 
+  ?preamble:bool ->
+  ?flat:bool ->
+  ?strip_anchors:bool ->
+  ?base:string ->
+  ?menu:string ->
+  ?subproject:string ->
+  ?menu_current:string ->
+  ?leftnav:string ->
+  ?mdlink:string ->
+  template:string ->
+  current:string ->
+  string ->
+  string
+```
+`page ~template ~current odoc_html` builds a full page: extract the odoc parts, [`Render.html`](./Wodoc-Render.md#val-html) the content fragment (the template chrome is never rendered), fill the template holes, then [`mark_current`](./#val-mark_current).
+
+- `preamble` (default `true`): fill `{{preamble}}` with the page `<h1>` title block; pass `false` for pages that should not show a title.
+- `flat` (default `false`): for full-width pages whose containers span the odoc preamble/content boundary, concatenate the inner preamble and content (dropping odoc's wrappers) into `{{content}}` and leave `{{preamble}}` empty.
+- `strip_anchors` (default `true`): drop odoc's heading hover-anchors.
+- `base` (default `""`): fills `{{base}}`, the relative path from the page to the doc root (e.g. `"."`, `".."`, `"../.."`), so a version's internal links stay within that version and never mention it.
+- `menu` (default `""`): fills `{{menu}}` with the shared site menu fragment (header, top menu, drawer). The fragment may carry its own holes (`{{subproject}}`, `{{base}}`, `{{leftnav}}`); the first two are filled here, `{{leftnav}}` is left for the caller. Lets every page share one menu source.
+- `subproject` (default `""`): fills `{{subproject}}` (the sub-project name shown next to the Ocsigen logo); empty on the vitrine.
+- `menu_current` (default `""`): like `current` but for the menu's current *project* entry (`data-wodoc-page=<project>`), kept separate from `current` so a project page can highlight both its menu entry and its in-page nav.
+- `leftnav` (default `""`): fills every `{{leftnav}}` hole (the drawer's mobile menu and the left column share one source), so the navigation is defined once instead of being `sed`\-expanded into both slots.
+- `mdlink` (default `""`): fills `{{mdlink}}` with the page's `<link rel="alternate" type="text/markdown">` element pointing at its Markdown twin (or `""` when there is no twin), so AIs/LLMs can discover the `.md` version of any page.

dev/wodoc/Wodoc-Assemble.md

@@ -0,0 +1,55 @@
+
+# Module `Wodoc.Blog`
+
+```ocaml
+type post = {
+  date : string; (* publication date "YYYY-MM-DD", taken from the file name *)
+  slug : string; (* the file-name part after the date, e.g. "first-post" *)
+  src : string; (* path to the post's .mld source *)
+  path : string; (* deployed page path, relative to the version root, e.g. "blog/first-post.html" *)
+  title : string; (* the post's {1 …} / {0 …} heading, as plain text *)
+  author : string; (* odoc @author …, plain text ("" when absent) *)
+  excerpt : string; (* first paragraph of the body, plain text (may be "") *)
+}
+```
+```ocaml
+val posts : Config.blog -> post list
+```
+`posts blog`: the posts found in `blog.dir` (file names `YYYY-MM-DD-slug.mld`), newest first. Files that do not match the dated naming are skipped.
+
+```ocaml
+val nav_section : Config.blog -> post list -> Config.section
+```
+`nav_section blog posts`: a synthetic left-nav [`Config.section`](./Wodoc-Config.md#type-section) listing the posts (heading `blog.heading`, one link per post), to splice into the config nav. The link label is "date — title".
+
+```ocaml
+val nav_html : base:string -> Config.blog -> post list -> string
+```
+`nav_html ~base blog posts`: the blog's left-nav block as a `<nav class="api-nav manual-nav">` (an `<h3>` \+ one `<li>` per post), rendered like a manual nav section so the shared CSS styles it. For the low-level `wodoc assemble --leftnav` path; the turn-key `wodoc build` path splices [`nav_section`](./#val-nav_section) instead. `base` is the page's relative path to the blog root.
+
+```ocaml
+val feed : 
+  base_url:string ->
+  blog_path:string ->
+  feed_path:string ->
+  title:string ->
+  author:string ->
+  post list ->
+  string
+```
+`feed ~base_url ~blog_path ~feed_path ~title ~author posts`: an Atom feed of the posts (newest first), for syndication (e.g. OCaml Planet). `base_url` is the site origin; a post's URL is `base_url ^ blog_path ^ "/" ^ post.path`; the feed advertises itself at `base_url ^ feed_path`. Entry bodies are the post excerpt as an HTML summary; the feed `updated` is the newest post's date.
+
+```ocaml
+val latest_fragment : base:string -> Config.blog -> post list -> string
+```
+`latest_fragment ~base blog posts`: the HTML fragment that the `{%wodoc:blog-latest%}` marker expands to — a `<ul class="wodoc-blog-list">` of the `blog.latest` most recent posts (title, date, author, excerpt, link), each link prefixed with `base` (the per-page relative root). Empty when there are no posts.
+
+```ocaml
+val marker : string
+```
+the marker the landing uses to request [`latest_fragment`](./#val-latest_fragment). wodoc rewrites `{%wodoc:blog-latest%}` to this HTML comment in [`Preprocess`](./Wodoc-Preprocess.md); [`expand`](./#val-expand) turns it back into the fragment.
+
+```ocaml
+val expand : fragment:string -> string -> string
+```
+`expand ~fragment html`: replace every [`marker`](./#val-marker) comment in `html` with `fragment`. A no-op when the page carries no marker.

dev/wodoc/Wodoc-Blog.md

@@ -0,0 +1,150 @@
+
+# Module `Wodoc.Build`
+
+```ocaml
+val read_file : string -> string
+```
+```ocaml
+val write_file : string -> string -> unit
+```
+```ocaml
+val is_url : string -> bool
+```
+```ocaml
+val origin_of : string -> string option
+```
+```ocaml
+val read_menu : string -> string
+```
+```ocaml
+val mkdir_p : string -> unit
+```
+```ocaml
+val html_files : string -> string -> string list
+```
+```ocaml
+val base_of : string -> string
+```
+```ocaml
+val replace_hole : string -> string -> string -> string
+```
+```ocaml
+val esc : string -> string
+```
+```ocaml
+val default_highlight : string
+```
+```ocaml
+val template : ?body_extra:string -> ?extra_script:string -> Config.t -> string
+```
+```ocaml
+val docversion : latest:string option -> string list -> string
+```
+```ocaml
+val page_toc : string
+```
+```ocaml
+val nav_href : string -> string
+```
+```ocaml
+val nav_link : int -> Config.entry -> string
+```
+```ocaml
+val render_items : Stdlib.Buffer.t -> int -> Config.item list -> unit
+```
+```ocaml
+val manual_nav : Config.t -> string
+```
+```ocaml
+val leftnav : latest:string option -> Config.t -> string list -> string
+```
+```ocaml
+val latest_target : root:string -> string option
+```
+```ocaml
+val compare_version : string -> string -> int
+```
+```ocaml
+val version_names : root:string -> ?extra:string list -> unit -> string list
+```
+```ocaml
+val versions : out:string -> label:string -> string list
+```
+```ocaml
+val write_manifest : root:string -> unit
+```
+```ocaml
+val asset_re : Str.regexp
+```
+```ocaml
+val local_assets : menu:string -> out:string -> unit
+```
+```ocaml
+val cs_switch : Config.cs_side list -> string
+```
+```ocaml
+val cs_switch_script : Config.t -> Config.cs_side list -> string
+```
+```ocaml
+val cs_leftnav : 
+  latest:string option ->
+  versions:string list ->
+  switch:string ->
+  manual_nav:string ->
+  api_nav:string ->
+  string
+```
+```ocaml
+val topdir : string -> string option
+```
+```ocaml
+val side_for : Config.cs_side list -> string -> Config.cs_side option
+```
+```ocaml
+val side_of : Config.cs_side list -> string -> string
+```
+```ocaml
+val drop_prefix : string -> string -> string
+```
+```ocaml
+val cs_current : Config.cs_side list -> string -> string
+```
+```ocaml
+val nav_entry_paths : Config.t -> string list
+```
+```ocaml
+val strip_index : string -> string
+```
+```ocaml
+val current_of_page : string -> string list -> string
+```
+```ocaml
+val md_twin : string -> string
+```
+```ocaml
+val md_alternate : 
+  md_src:string option ->
+  base:string ->
+  rel:string ->
+  orel:string ->
+  string
+```
+```ocaml
+val nav_md_order : Config.t -> string list
+```
+```ocaml
+val run : 
+  Config.t ->
+  src:string ->
+  md_src:string option ->
+  out:string ->
+  label:string ->
+  menu:string ->
+  assets_dir:string ->
+  local:bool ->
+  set_latest:bool ->
+  unit
+```
+```ocaml
+val release : site:string -> from:string -> version:string -> unit
+```