[repo-assist] docs: document embedding images in XML/Markdown doc comments - #1332
Draft
github-actions[bot] wants to merge 1 commit into
Draft
github-actions[bot] wants to merge 1 commit into
github-actions[bot] wants to merge 1 commit into
Conversation
Closes long-standing confusion tracked in issue #928 (fsdocs does not copy source-tree images referenced from XML/Markdown /// doc comments; it only resolves such assets from the docs input directory using site-root-relative paths). Adds a verified 'Images in Doc Comments' section to docs/apidocs.fsx cross-referencing the existing --saveimages pipeline for literate .fsx scripts. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This branch has not been 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.
🤖 This PR was created by Repo Assist, an automated AI assistant.
Summary
Documents how to embed images in XML/Markdown
///doc comments indocs/apidocs.fsx. This behaviour previously had no documentation anywhere in the repo — it was only explained ad hoc by a Repo Assist comment on issue #928.Verified against current code (
src/FSharp.Formatting.ApiDocs/SymbolReader.fs,src/fsdocs-tool/BuildCommand.fs):fsdocsnever copies source-tree images referenced from///doc comments, since it has no way to resolve a path relative to the source file. The documented workaround (place images under thedocsinput directory, e.g.docs/content/images/, and reference them with a site-root-relative/content/images/...path) matches the actual copy/substitution behaviour. Cross-references the existing--saveimagesdocs for the separate literate.fsxscript image pipeline, which behaves differently (path-relative resolution).Changes
docs/apidocs.fsx: added an "Images in Doc Comments" section under "Classic XML Doc Comments" / before "Markdown Comments".RELEASE_NOTES.md: added an[Unreleased]entry.Test Status
dotnet fantomas build.fsx src tests docs --check— clean (docs.fsxfiles are.fantomasignored, no formatting issues).fsdocs-tool(Release) and ranfsdocs build --input docsagainst the updateddocs/apidocs.fsx— content generation succeeded (18 pages), and the generatedapidocs.htmlcontains the new "Images in Doc Comments" section rendered correctly.Relates to #928 (does not close it — the underlying feature request for automatic image copying from XML doc comments is still open; this PR only documents the current, correct workaround).
Add this agentic workflow to your repo
To install this agentic workflow, run