Repository navigation
Show the capability directory on the Erlang, OCaml and Common Lisp reference pages - #317
Merged
Merged
Conversation
…ry references
why: Lua, Rust and TypeScript server pages draw their "What is on here"
directory as a table, but the shell only folds a directory whose
reference lines use a spelling it knows for the port. Erlang, OCaml
and Common Lisp fell back to the shared rustdoc, XML doc, Javadoc and
Go forms, so a directory written in any of the three would stay prose.
what:
- Read EEP-48 code spans (`fun/1`, `mod:fun/1`, `t:type/0`,
`c:callback/1`, `m:module`) for Erlang
- Read odoc references ({!Client.connect}, {{!x}text}) for OCaml
- Read package-qualified code spans (`libtmux:fetch-snapshot`) for
Common Lisp
- Cover each in the per-port directory table, with an atom, a tuple,
plain code spans and unqualified names as negatives
why: "A tmux server" pointed OCaml at Libtmux_unix.Client.t, an opaque type alias with no documentation and no members, so the page readers reach from every other port's server page and the core home was empty. The module holds the client's functions and its documentation, as Erlang's tmux_server and Elixir's LibTmux.Server do. what: - Point the server concept and its Eio variant at Libtmux_unix.Client and Libtmux_eio.Client - Point the core home's server object at Libtmux_unix.Client
why: The client class page had no Members list, unlike every other port's server page: Common Lisp operations are package functions, so the adapter filed all of them under the package. what: - Give each libtmux function whose first required parameter is the client the client class as its parent; macros, functions without a client first and other packages keep the package - Show such a member by its package-qualified name, as Common Lisp writes it, never through the class - Test both, with controls for a function without a client, one that takes the client later and another package's function
why: Mapping the OCaml server concept to Libtmux_unix.Client left the concept test expecting the Client.t type, so the test failed on the branch before any model changed. what: - Expect the server concept of OCaml to resolve to the Libtmux_unix.Client module symbol, which carries the capability directory
…ges are HTML why: libtmux-erlang writes its README header in HTML so ex_doc renders it: a centered <h1> title and <a><img></a> badges. Staging read only a Markdown title and Markdown badge images, so the Getting started page kept a second h1 and hotlinked three img.shields.io badges and a GitHub Actions badge that every other port serves from the site's origin. The Erlang pin to the current master fails the off-origin badge tests until staging reads the HTML form. what: - Read a centered <h1> title as the README title, as a centered Markdown heading already is, so the page keeps one heading - Render the img.shields.io badges inside an HTML block to files on the site's origin and drop a status badge with its link, as for Markdown badges; refuse an HTML badge the localizer cannot render - Share the badge rendering between the Markdown and HTML paths - Expect a staged README written as HTML to hold no off-origin badge and no <h1>, and fail the badge unit test without the HTML path
why: The Erlang reference page cannot show the "What is on here" capability directory until the model carries the prose it is built from. libtmux-erlang PR #15 adds that directory to the tmux_server module docs, and the committed model, guide cache and manifest still described the pre-PR master 539c7297c. The pin is the PR head, which merges into master with a merge commit, so the revision stays reachable after the merge. what: - Pin Erlang to libtmux/libtmux-erlang@33fd7fe98 and regenerate its model and path data (exported with OTP 29.1.2 and the same exporter digest as before), tmux usage, guide cache, manifest packages and mention index with the repository's generators - Adopt the source change between the pins: the tmux_server module doc gains the capability directory, and no other declaration or doc comment changed, so the other 324 symbols move only by line number - Re-anchor the three tmux_server.erl evidence lines of the reviewed usage entries to their new positions; no claim or rule changed - Take the rewritten README and reader guides into the guide cache: the README gains the send-keys and capture, query planner and command batching sections and an HTML header with badges, which staging now reads, and the guides cut their paragraph walls - Add the three programs the repository gained, typing_demo.erl, plan_demo.erl and batch_demo.erl, to the examples index, link all eighteen at the new revision, and expect eighteen in the index test - Leave the landing example and its recording at the revision where the program was recorded: examples/ gained files but the recorded program is unchanged Source refs: libtmux/libtmux-erlang PR #15 head 33fd7fe985454e375d5ac8533043cabf4a0b2fa5, previous pin 539c7297ceae65a1cf683e0836eae0a1ccd34d64.
why: The OCaml reference page cannot show the "What is on here" capability directory until the model carries the prose it is built from. libtmux-ocaml PR #10 adds that directory to the Client module docs, and the committed model, guide cache and manifest still described the pre-PR master 205dfda49. The pin is the PR head, which merges into master with a merge commit, so the revision stays reachable after the merge. what: - Pin OCaml to libtmux/libtmux-ocaml@ca4b6c0cb and regenerate its model and path data (exported with OCaml 5.5.2 and odoc-parser 3.2.2, the toolchain recorded in the previous model), tmux usage, guide cache and manifest packages with the repository's generators; the mention index is unchanged - Adopt the source change between the pins: the Libtmux_unix.Client module doc gains the capability directory, and the examples moved their docs:begin markers so the code attached to fifteen other symbols, such as Client.capture, Window.panes and Workspace.client, is now the marked region of the program - Re-anchor the unix/streaming.ml evidence lines of the reviewed usage entries to their new positions; no claim or rule changed - Take the rewritten reader guides into the guide cache: getting started, bootstrap, graph, queries, control, streaming, showcases, packages, compatibility, status and workspaces - Refresh the example sources cached at the model revision: the send-keys showcase now splits a pane, captures its screen and resizes it, and the graph showcase, whose excerpts feed the landing page, moved its marked region and module aliases without changing the excerpted lines - Describe the send-keys showcase accordingly, add the two programs the repository gained, query_plan.ml and workspace_plan.ml, to the examples index, link all twenty-two at the new revision, and expect twenty-two in the index test - Leave the Core player recording at the revision where it was recorded: re-recording the showcase is a separate step Source refs: libtmux/libtmux-ocaml PR #10 head ca4b6c0cb8ccccfe54d93ec67067070a9d33aeb9, previous pin 205dfda49742592b479247049d186956e4a4cfe9.
…tory why: The Common Lisp reference page cannot show the "What is on here" capability directory until the model carries the prose it is built from, and the client class cannot list its operations as members until the model is regenerated with the reparenting the extractor now applies. libtmux-lisp PR #10 adds the directory to the client class docstring, and the committed model, guide cache and manifest still described the pre-PR master e6f319c42. The pin is the PR head, which merges into master with a merge commit, so the revision stays reachable after the merge. what: - Pin Common Lisp to libtmux/libtmux-lisp@a29c6b96e and regenerate its model, sidebar and path data (exported with SBCL 2.6.10 and ASDF 3.3.7, the runtime recorded in the previous model, from a clean checkout with the locked dependencies), tmux usage, guide cache, manifest packages and mention index with the repository's generators - Adopt the source change between the pins: the client class docstring gains the capability directory, and the 86 client-first functions now have the client class as their parent, which is the only other model difference besides line numbers - Keep every reviewed tmux usage claim: no source file under src/ moved a cited line, so only the usage file's revision binding changes - Take the rewritten README and reader guides into the guide cache: the README gains linked API sections and the guides break their paragraphs into bullets - Refresh the workspace example cached for the landing page at the model revision: workspace.lisp gained package and explain regions, and the excerpted lines are unchanged - Add the program the repository gained, drive-panes.lisp, to the examples index, link all eleven files at the new revision, and expect seven programs and four support files in the index test - Leave the Core player recording at the revision where it was recorded: re-recording the quickstart is a separate step Source refs: libtmux/libtmux-lisp PR #10 head a29c6b96e1c78501dff5073b538ae3180b0e63e3, previous pin e6f319c4257789cfe39547af001c718975f0a2ef.
…dels carry their directory why: The directory readers for Erlang, OCaml and Common Lisp were tested against synthetic prose only, so a model pinned before the native docs gained their directory passed every test while the reference page showed no table. The same gap hid that the Lisp client class had no members until the model was regenerated with the reparenting. what: - Fold the real doc of tmux_server, Libtmux_unix.Client and libtmux:client with groupDirectory and expect a directory of eight rows, each naming at least one member - Expect the Common Lisp client class to be the parent of its client-first functions, such as fetch-snapshot and send-text - Both checks fail on the models pinned before the three repins: no directory on any of the three owners and no members on the client class
… longer makes why: At the new Common Lisp pin the concurrency guide says "There is no asyncio or event-loop integration" in plain prose; the earlier text put `asyncio` in a code span, which linked Python's asyncio module. The evidence still held that destination, so the destination check failed: the evidence names a link no source generates. what: - Remove the docs.python.org asyncio module row from the API destination evidence (`verify-api-destinations.mjs --missing`: no request made, only the row no source generates is dropped)
why: libtmux-perl's README now shows a shields CPAN version badge for each distribution (cpan/v/LibTmux and the Async and Workspace distributions). Staging the README from master threw "unsupported badge", so the Perl docs build stopped before it published. what: - Map shields' cpan version service (label "cpan", no qualifier) to the registry version of the named distribution, which registry.json already carries for all three Perl distributions - Cover it with the registry badge table in port-guide-badges.test.ts
why: The Java Gradle install named libtmux-bom:0.1.0 and the Swift
Package.swift install named from: "0.1.0" as literals, so the registry
refresh to Java 0.1.2 and Swift 0.1.1 left both landing pages offering
the first release while every other port's install moved.
what:
- Write both installs with the {version} placeholder that installsFor
fills from the registry entry (or the page's own release on a versioned
tree)
- Word the Swift note for any release
- Test that the Java and Swift installs name the registry's version
…port's mount why: Erlang's README header is HTML (written for ex_doc), so its localized badges reach the page as raw `<img src="/badges/…">` tags. The site-root rewrite only visits elements, so those paths stayed root-absolute: the PR preview's isolation check found them escaping /pr-317/, and on libtmux.org /badges/ at the root answers 403, so the badges would ship broken. what: - Rewrite `src="/badges/…"` inside raw HTML nodes with the same own-mount rule a Markdown badge takes (the port build's mount, under any preview root) - Test both the port mount and a preview root for an HTML header badge
This branch was successfully deployed
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.
The Erlang, OCaml and Common Lisp reference pages showed no "What is on here" capability directory, the table that groups a port's main type by task on the Lua, Rust and TypeScript pages. Their doc comments had no directory, and the shell did not read their reference syntax.
What changes
Native directories (pinned at the open native PR heads; each merges into its master with a merge commit, so the pinned SHA stays in master's history)
tmux_servermodule docs (libtmux-erlang#15,33fd7fe98).Libtmux_unix.Clientmodule docs (libtmux-ocaml#10,ca4b6c0cb).clientclass docstring (libtmux-lisp#10,a29c6b96e).Shell
site/src/lib/api-directory.tsreads each port's own reference spelling in a directory row: EEP-48`m:module`and`mod:fun/1`, odoc{!Client.connect}and{{!Client.connect}text}, and package-qualified Lisp symbols such as`libtmux:fetch-snapshot`.packages/api-model/src/languages/lisp.tslists a function whose first required parameter is aclientas a member of theclientclass (86 functions), so the class page has members to group.Libtmux_unix.Client(variantLibtmux_eio.Client).scripts/stage-port-docs.mjsstages a README whose header and badges are HTML (Erlang's, written for ex_doc).Data
Effect
groupDirectoryon each pinned model's owner symbol:tmux_serverLibtmux_unix.Clientlibtmux:clientVerification
site/test/api-prose.test.tsfails on the previous models and passes on these.astro check, oxlint, and every touched generator's--check.After merge
IAM trust for the merge revision, then the Erlang, OCaml and Common Lisp repins and publishes, once their native PRs have merged.