[repo-assist] docs: describe Literate scripts as a lightweight doc-testing mechanism - #1267
Draft
github-actions[bot] wants to merge 1 commit into
Draft
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>
10 tasks
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.
🤖 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