[repo-assist] docs: describe Literate scripts as a lightweight doc-testing mechanism - #1267
Merged
Merged
Conversation
Addresses feedback in #1221 by explicitly documenting that Literate's --eval execution of embedded F# code, combined with (*** include-output ***) and (*** include-value ***), functions as a low-effort doc-test workflow: code samples are executed for real and failures surface at build time. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This was referenced Aug 27, 2026
Migrate the fsdocs watch server to Suave 3's Task-based socket API: the websocket handler and reload broadcast now use ValueTask/Result, the removed Suave.Logging module is dropped, and the server task from startWebServerAsync is already hot so it no longer needs Async.Start. While migrating, fix a crash in watch mode: clients that disconnect without a close handshake stayed registered, and broadcasting to such a dead socket throws ObjectDisposedException in Suave 3, killing the whole watch process. Clients are now deregistered whenever their connection ends, and the broadcast tolerates stale sockets. Also in watch mode, the logo now links to the locally hosted site root instead of the production URL (even when <FsDocsLogoLink> is set), and the console no longer logs websocket connection chatter on every page reload. Release builds are unaffected. Bump Fun.Build from 1.0.4 to 1.1.18 and make build.fsx directly executable via a dotnet fsi shebang. Release notes: 22.2.0.
* Move the Mermaid example from docs/sidebyside/sidemermaid.md to docs/mermaid.md and rewrite it around plain ```mermaid fenced blocks promoted by a docs/_body.html script, the pattern used by the fantomas docs. The source now renders on GitHub and the recipe page actually renders its own diagrams. * Add Docs pipeline to easily launch documentation locally.
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
2 participants
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.
🤖 This PR was created by Repo Assist, an automated AI assistant.
What
Adds a short "Using Literate scripts as doc tests" section to
docs/literate.fsx, explaining that Literate's--evalexecution of embedded F# code (via FSI), combined with(*** include-output ***)/(*** include-value ***), already provides a low-effort form of doc-testing: sample code is executed for real when docs are built, and failures surface immediately rather than silently drifting out of sync with the API.Why
Issue #1221 asks for the
Literatelibrary's doc-testing capability to be given more visibility, since users are often unaware F# has any doc-test-like tool. Documenting this existing behaviour directly in the main literate-scripts reference page is a low-risk, immediately useful first step (as suggested in Repo Assist's earlier comment on that issue), without requiring a new repo/package split, which is a bigger decision for maintainers.Trade-offs
Test Status
dotnet fantomas docs/literate.fsx --check— passes (no formatting issues).dotnet build FSharp.Formatting.sln --configuration Release— succeeded.fsdocs build --clean— succeeded; verified the new section renders correctly in generatedliterate.html.Related: #1221
Add this agentic workflow to your repo
To install this agentic workflow, run