Merge branch 'main' into repo-assist/fix-191-commonmark-atx-headings-26ab2fbf1051d319

Author: nojaf

RELEASE_NOTES.md

@@ -3,10 +3,12 @@
 ## [Unreleased]
 
 ### Added
+* Add "Copy" button to all code blocks in generated documentation, making it easy to copy code samples to the clipboard. [#72](https://github.com/fsprojects/FSharp.Formatting/issues/72)
 * Add `<FsDocsAllowExecutableProject>true</FsDocsAllowExecutableProject>` project file setting to include executable projects (OutputType=Exe/WinExe) in API documentation generation. [#918](https://github.com/fsprojects/FSharp.Formatting/issues/918)
 * Add `{{fsdocs-logo-alt}}` substitution (configurable via `<FsDocsLogoAlt>` MSBuild property, defaults to `Logo`) for accessible alt text on the header logo image. [#626](https://github.com/fsprojects/FSharp.Formatting/issues/626)
 
 ### Fixed
+* Fix doc generation failure for members with 5D/6D+ array parameters by correctly formatting array type signatures in XML doc format (e.g. `System.Double[0:,0:,0:,0:,0:]` for a 5D array). [#702](https://github.com/fsprojects/FSharp.Formatting/issues/702)
 * Fix `_menu_template.html` and `_menu-item_template.html` being copied to the output directory. [#803](https://github.com/fsprojects/FSharp.Formatting/issues/803)
 * Fix `ApiDocMember.Details.ReturnInfo.ReturnType` returning `None` for properties that have both a getter and a setter. [#734](https://github.com/fsprojects/FSharp.Formatting/issues/734)
 * Improve error message when a named code snippet is not found (e.g. `(*** include:name ***)` with undefined name now reports the missing name clearly). [#982](https://github.com/fsprojects/FSharp.Formatting/pull/982)
@@ -15,6 +17,7 @@
 * Strip `#if SYMBOL` / `#endif // SYMBOL` marker lines from `LiterateCode` source before syntax-highlighting so they do not appear in formatted output. [#693](https://github.com/fsprojects/FSharp.Formatting/issues/693)
 * Fix incorrect column ranges for inline spans (links, images, inline code) in the Markdown parser — spans and subsequent literals now report correct `StartColumn`/`EndColumn` values. [#744](https://github.com/fsprojects/FSharp.Formatting/issues/744)
 * Normalize `--projects` paths to absolute paths before passing to the project cracker, fixing failures when relative paths are supplied. [#793](https://github.com/fsprojects/FSharp.Formatting/issues/793)
+* Fix incorrect paragraph indentation for loose list items: a paragraph indented at the outer list item's continuation level is now correctly treated as a sibling of surrounding sublists rather than being absorbed into the first sublist item's body. [#347](https://github.com/fsprojects/FSharp.Formatting/issues/347)
 * Improve CommonMark compliance for ATX headings: reject `#` not followed by a space (e.g. `#NoSpace` is now a paragraph), reject more than 6 `#` characters as a heading, support 0–3 leading spaces before the opening `#` sequence, and fix empty content when the entire header body is a closing `###` sequence. [#191](https://github.com/fsprojects/FSharp.Formatting/issues/191)
 
 ### Changed

docs/_template.html

@@ -97,6 +97,7 @@
 <script type="module" src="{{root}}content/fsdocs-details-toggle.js"></script>
 <script type="module" src="{{root}}content/fsdocs-theme.js"></script>
 <script type="module" src="{{root}}content/fsdocs-search.js"></script>
+<script type="module" src="{{root}}content/fsdocs-copy-button.js"></script>
 {{fsdocs-body-extra}}
 </body>
 </html>

docs/content/fsdocs-copy-button.js

@@ -0,0 +1,75 @@
+// Adds a "Copy" button to every code block so readers can easily copy snippets.
+function createCopyButton() {
+    const button = document.createElement('button')
+    button.className = 'copy-code-button'
+    button.setAttribute('aria-label', 'Copy code to clipboard')
+    button.textContent = 'Copy'
+    return button
+}
+
+function attachCopyHandler(button, getText) {
+    button.addEventListener('click', function () {
+        const text = getText()
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+            navigator.clipboard.writeText(text).then(
+                function () {
+                    button.textContent = 'Copied!'
+                    setTimeout(function () {
+                        button.textContent = 'Copy'
+                    }, 2000)
+                },
+                function () {
+                    button.textContent = 'Failed'
+                    setTimeout(function () {
+                        button.textContent = 'Copy'
+                    }, 2000)
+                }
+            )
+        } else {
+            // Fallback for non-HTTPS environments
+            const el = document.createElement('textarea')
+            el.value = text
+            document.body.appendChild(el)
+            el.select()
+            document.execCommand('copy')
+            document.body.removeChild(el)
+            button.textContent = 'Copied!'
+            setTimeout(function () {
+                button.textContent = 'Copy'
+            }, 2000)
+        }
+    })
+}
+
+document.addEventListener('DOMContentLoaded', function () {
+    // table.pre blocks (F# highlighted code, sometimes with line numbers)
+    document.querySelectorAll('table.pre').forEach(function (table) {
+        const wrapper = document.createElement('div')
+        wrapper.className = 'code-block-wrapper'
+        table.parentNode.insertBefore(wrapper, table)
+        wrapper.appendChild(table)
+
+        const button = createCopyButton()
+        wrapper.appendChild(button)
+
+        const snippet = table.querySelector('.snippet pre')
+        attachCopyHandler(button, function () {
+            return (snippet || table).innerText
+        })
+    })
+
+    // Standard pre > code blocks (Markdown fenced code, standalone fssnip, etc.)
+    // Skip those already handled inside table.pre above.
+    document.querySelectorAll('pre > code').forEach(function (code) {
+        if (code.closest('table.pre')) return
+        const pre = code.parentElement
+        pre.classList.add('has-copy-button')
+
+        const button = createCopyButton()
+        pre.appendChild(button)
+
+        attachCopyHandler(button, function () {
+            return code.innerText
+        })
+    })
+})

docs/content/fsdocs-default.css

@@ -731,7 +731,7 @@ h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
     font-size: inherit;
 }
 
-table.pre, #content > pre.fssnip {
+table.pre, #content > pre.fssnip, .code-block-wrapper > table.pre {
     border: 1px solid var(--code-fence-border-color);
 }
 
@@ -740,6 +740,47 @@ table.pre, pre.fssnip.highlighted {
     padding: var(--spacing-200);
 }
 
+/* Copy code button */
+.code-block-wrapper {
+    position: relative;
+    display: block;
+    margin: var(--spacing-300) 0;
+}
+
+.code-block-wrapper > table.pre {
+    margin: 0;
+}
+
+pre.has-copy-button {
+    position: relative;
+}
+
+.copy-code-button {
+    position: absolute;
+    top: var(--spacing-100);
+    right: var(--spacing-100);
+    padding: var(--spacing-50) var(--spacing-100);
+    background-color: var(--header-background);
+    border: 1px solid var(--header-border);
+    border-radius: var(--radius);
+    color: var(--text-color);
+    cursor: pointer;
+    font-family: var(--system-font);
+    font-size: var(--font-50);
+    opacity: 0;
+    transition: opacity 0.2s ease-in-out;
+    z-index: 10;
+
+    &:hover {
+        background-color: var(--menu-item-hover-background);
+    }
+}
+
+pre.has-copy-button:hover .copy-code-button,
+.code-block-wrapper:hover .copy-code-button {
+    opacity: 1;
+}
+
 table.pre .snippet pre.fssnip {
     padding: 0;
     margin: 0;

docs/content/fsdocs-tips.js

@@ -45,12 +45,16 @@ function showTip(evt, name, unique, owner) {
 }
 
 function Clipboard_CopyTo(value) {
-    const tempInput = document.createElement("input");
-    tempInput.value = value;
-    document.body.appendChild(tempInput);
-    tempInput.select();
-    document.execCommand("copy");
-    document.body.removeChild(tempInput);
+    if (navigator.clipboard) {
+        navigator.clipboard.writeText(value);
+    } else {
+        const tempInput = document.createElement("input");
+        tempInput.value = value;
+        document.body.appendChild(tempInput);
+        tempInput.select();
+        document.execCommand("copy");
+        document.body.removeChild(tempInput);
+    }
 }
 
 window.showTip = showTip;

src/FSharp.Formatting.ApiDocs/GenerateModel.fs

@@ -750,20 +750,41 @@ module internal CrossReferences =
                         else
                             ""
 
+                    let rec formatTypeForXmlDocSig (typ: FSharpType) =
+                        if typ.IsGenericParameter then
+                            typeArgsMap.[typ.GenericParameter.Name]
+                        elif typ.HasTypeDefinition && typ.TypeDefinition.IsArrayType then
+                            let elementTypeName = formatTypeForXmlDocSig typ.GenericArguments.[0]
+                            let rank = typ.TypeDefinition.ArrayRank
+
+                            if rank = 1 then
+                                elementTypeName + "[]"
+                            else
+                                let dims = String.concat "," (Array.create rank "0:")
+                                elementTypeName + "[" + dims + "]"
+                        elif typ.HasTypeDefinition then
+                            let baseName =
+                                match typ.TypeDefinition.TryFullName with
+                                | Some fullName -> fullName
+                                | None -> typ.TypeDefinition.CompiledName
+
+                            if typ.GenericArguments.Count > 0 then
+                                let args = typ.GenericArguments |> Seq.map formatTypeForXmlDocSig |> String.concat ","
+
+                                baseName + "{" + args + "}"
+                            else
+                                baseName
+                        else
+                            typ.Format(FSharpDisplayContext.Empty)
+
                     let paramList =
                         if
                             memb.CurriedParameterGroups.Count > 0
                             && memb.CurriedParameterGroups.[0].Count > 0
                         then
                             let head = memb.CurriedParameterGroups.[0]
 
-                            let paramTypeList =
-                                head
-                                |> Seq.map (fun param ->
-                                    if param.Type.IsGenericParameter then
-                                        typeArgsMap.[param.Type.GenericParameter.Name]
-                                    else
-                                        param.Type.TypeDefinition.FullName)
+                            let paramTypeList = head |> Seq.map (fun param -> formatTypeForXmlDocSig param.Type)
 
                             "(" + System.String.Join(", ", paramTypeList) + ")"
                         else

src/FSharp.Formatting.Markdown/MarkdownParser.fs

@@ -819,6 +819,33 @@ let (|LinesUntilListOrUnindented|) lines =
         | StringPosition.WhiteSpace :: StringPosition.WhiteSpace :: _ -> true
         | _ -> false)
 
+/// Returns the effective number of leading spaces in a string, treating each tab as 4 spaces.
+let private tabAwareLeadingSpaces (s: string) =
+    let mutable spaces = 0
+    let mutable i = 0
+
+    while i < s.Length && (s.[i] = ' ' || s.[i] = '\t') do
+        spaces <- spaces + (if s.[i] = '\t' then 4 else 1)
+        i <- i + 1
+
+    spaces
+
+/// Splits input into lines for a loose list item continuation (when a blank line follows
+/// the first line of the item). Unlike LinesUntilListOrUnindented, this does not stop at
+/// indented list starts — it captures all continuation content at or above the item's
+/// content column (endIndent). It stops at truly unindented content (0 leading spaces),
+/// double blank lines, or a blank line followed by content with fewer leading spaces than
+/// endIndent (indicating the content belongs to an outer list item, not this one).
+let (|LinesUntilListOrUnindentedLoose|) endIndent lines =
+    lines
+    |> List.partitionUntilLookahead (function
+        | StringPosition.Unindented :: _
+        | StringPosition.WhiteSpace :: StringPosition.WhiteSpace :: _ -> true
+        | StringPosition.WhiteSpace :: (s, _) :: _ ->
+            let leading = tabAwareLeadingSpaces s
+            leading > 0 && leading < endIndent
+        | _ -> false)
+
 /// Recognizes a list item until the next list item (possibly nested) or end of a list.
 /// The parameter specifies whether the previous line was simple (single-line not
 /// separated by a white line - simple items are not wrapped in <p>)
@@ -829,9 +856,19 @@ let (|ListItem|_|) prevSimple lines =
     //
     // Then take more things that belong to the item -
     // the value 'more' will contain indented paragraphs
-    | (ListStart(kind, startIndent, endIndent, item) as takenLine) :: LinesUntilListOrWhite(continued,
-                                                                                            (LinesUntilListOrUnindented(more,
-                                                                                                                        rest) as next)) ->
+    | (ListStart(kind, startIndent, endIndent, item) as takenLine) :: LinesUntilListOrWhite(continued, next) ->
+        // For loose items (blank line follows the first content line), use loose indentation
+        // rules: capture all continuation content at this item's indent level, including any
+        // nested list starts. For tight items, stop at list starts (original behaviour).
+        let more, rest =
+            match next with
+            | StringPosition.WhiteSpace :: _ ->
+                match next with
+                | LinesUntilListOrUnindentedLoose endIndent (m, r) -> m, r
+            | _ ->
+                match next with
+                | LinesUntilListOrUnindented(m, r) -> m, r
+
         let simple =
             match item with
             | StringPosition.TrimStartAndCount(_, spaces, _) when spaces >= 4 ->

tests/FSharp.Markdown.Tests/Markdown.fs

@@ -1285,3 +1285,25 @@ let ``Don't replace links in generated code block in table`` () =
         |> properNewLines
 
     Markdown.ToHtml(doc, mdlinkResolver = mdlinkResolver) |> shouldEqual actual
+
+[<Test>]
+let ``Paragraph between sublists should not be absorbed into first sublist item (issue 347)`` () =
+    // Per CommonMark, a paragraph indented at the outer list item's continuation level
+    // should remain a sibling of the surrounding sublists, not be absorbed into the
+    // first sublist item's body.
+    let html =
+        "1.  List item\n\n    1. Subone\n\n    Paragraph\n\n    7. SubRestart\n\n5.  Another list item\n"
+        |> Markdown.ToHtml
+
+    // The paragraph must appear between the two sublists, not inside the first.
+    html |> should contain "<p>Paragraph</p>"
+
+    // There must be two separate ordered sub-lists.
+    let firstSublistEnd = html.IndexOf("</ol>")
+    let paragraphPos = html.IndexOf("<p>Paragraph</p>")
+    let secondSublistStart = html.LastIndexOf("<ol>")
+
+    // Paragraph comes after first sublist ends.
+    paragraphPos |> should be (greaterThan firstSublistEnd)
+    // Second sublist starts after paragraph.
+    secondSublistStart |> should be (greaterThan paragraphPos)