Fixes for <exclude/> support, with tests and docs.

Documentation on rebasing links
Issues fsprojects#786 , fsprojects#785

.gitignore

@@ -46,3 +46,4 @@ src/Common/AssemblyInfo.?s
 tests/FSharp.Literate.Tests/output1/
 .vscode/
 .DS_Store
+tests/FSharp.Literate.Tests/output2/

FSharp.Formatting.sln

@@ -83,6 +83,8 @@ Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "TestLib1", "tests\FSharp.Ap
 EndProject
 Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "TestLib2", "tests\FSharp.ApiDocs.Tests\files\TestLib2\TestLib2.fsproj", "{48EFFECF-ECB0-4DF3-A704-B56AB07557BF}"
 EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "TestLib3", "tests\FSharp.ApiDocs.Tests\files\TestLib3\TestLib3.fsproj", "{52B949AA-A3F7-4894-B713-804BAEB71118}"
+EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "csharpSupport", "tests\FSharp.ApiDocs.Tests\files\csharpSupport\csharpSupport.csproj", "{DA7BA2FA-447E-41F3-88D9-00CF3E052E2C}"
 EndProject
 Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "crefLib1", "tests\FSharp.ApiDocs.Tests\files\crefLib1\crefLib1.fsproj", "{A0C8DD00-BD08-48D6-B257-5A838E5DA819}"
@@ -193,6 +195,10 @@ Global
 		{48EFFECF-ECB0-4DF3-A704-B56AB07557BF}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{48EFFECF-ECB0-4DF3-A704-B56AB07557BF}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{48EFFECF-ECB0-4DF3-A704-B56AB07557BF}.Release|Any CPU.Build.0 = Release|Any CPU
+		{52B949AA-A3F7-4894-B713-804BAEB71118}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{52B949AA-A3F7-4894-B713-804BAEB71118}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{52B949AA-A3F7-4894-B713-804BAEB71118}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{52B949AA-A3F7-4894-B713-804BAEB71118}.Release|Any CPU.Build.0 = Release|Any CPU
 		{DA7BA2FA-447E-41F3-88D9-00CF3E052E2C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{DA7BA2FA-447E-41F3-88D9-00CF3E052E2C}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{DA7BA2FA-447E-41F3-88D9-00CF3E052E2C}.Release|Any CPU.ActiveCfg = Release|Any CPU

docs/apidocs.fsx

@@ -169,6 +169,63 @@ type GenericClass2<'T>() =
 /// and <see cref="M:TheNamespace.GenericClass2`1.GenericMethod``1(`0,``0)" />
 let referringFunction2 () = "result"
 
+(**
+### Classic XMl Doc Comments: Excluding APIs from the docs
+
+If you want to exclude modules or functions from the API docs you can use the `<exclude/>` tag.
+It needs to be set on a separate triple-slashed line, and can either appear on its own or as part
+of an existing `<summary>` (for example, you may wish to hide existing documentation while it's in progress).
+The `<exclude/>` tag can be the first or last line in these cases.
+
+Some examples:
+*)
+
+/// </exclude>
+module BottleKids1 =
+    let a = 42
+
+// Ordinary comment
+/// </exclude>
+module BottleKids2 =
+    let a = 43
+
+/// </exclude>
+/// BottleKids3 provides improvements over BottleKids2
+module BottleKids3 =
+    let a = 44
+
+/// BottleKids4 implements several new features over BottleKids3
+/// </exclude>
+module BottleKids4 =
+    let a = 45
+
+/// </exclude>
+/// <summary>
+/// BottleKids5 is all you'll ever need in terms of bottles or kids.
+/// </summary>
+module BottleKids5 =
+    let a = 46
+
+(**
+
+Note that the comments for `BottleKids3` (and `BottleKids4`) will generate a warning. This is because
+the `<exclude/>` tag will be parsed as part of the `summary` text, and so the documentation generator
+can't be completely sure you meant to exclude the item, or whether it was a valid part of the documentation.
+It will treat it as an exclusion was intended, but you may want to use explicit `<summary>` tags to remove
+the warning.
+
+The warning will be of the following format:
+```
+Warning: detected "<exclude/>" in text of "<summary>" for "M:YourLib.BottleKids4". Please see https://fsprojects.github.io/FSharp.Formatting/apidocs.html#Classic-XML-Doc-Comments
+```
+You will find that `[omit]` also works, but is considered part of the Markdown syntax and is
+deprecated for XML Doc comments. This will also produce a warning, such as this:
+
+```
+The use of `[omit]` and other commands in XML comments is deprecated, please use XML extensions, see https://github.com/fsharp/fslang-design/blob/master/tooling/FST-1031-xmldoc-extensions.md
+```
+
+*)
 (**
 
 ## Go to Source links
@@ -242,7 +299,7 @@ module Foo3 =
 ### Markdown Comments: Excluding APIs from the docs
 
 If you want to exclude modules or functions from the API docs you can use the `[omit]` tag.
-It needs to be set on a separate tripple-slashed line, but it could be either the first or the last:
+It needs to be set on a separate triple-slashed line, but it could be either the first or the last:
 
 Example as last line:
 *)
@@ -290,3 +347,17 @@ ApiDocs.GenerateHtml(
     template = Path.Combine(root, "templates", "template.html"),
     substitutions = []
 )
+
+
+(**
+## Rebasing Links
+
+The `root` parameter is used for the base of page and image links in the generated documentation, and by default is derived from the project's `<PackageProjectUrl>` property.
+
+In some instances, you may wish to override the value for `root` (perhaps for local testing). To do this, you can use the command-line argument `--parameters root <base>`.
+
+For example:
+```
+% dotnet fsdocs build --output public/docs --parameters root ../
+```
+*)

src/FSharp.Formatting.ApiDocs/GenerateHtml.fs

@@ -707,7 +707,7 @@ type HtmlRender(model: ApiDocModel, ?menuTemplateFolder: string) =
             printfn "  Generating %s" outFile
             SimpleTemplating.UseFileAsSimpleTemplate(substitutions, templateOpt, outFile)
 
-        for info in model.EntityInfos do
+        for info in model.EntityInfos |> List.filter (fun info -> not info.Entity.Exclude) do
             let content = div [] (entityContent info)
 
             let pageTitle = sprintf "%s (%s)" info.Entity.Name collectionName

src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs

@@ -447,7 +447,7 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
             printfn "  Generating %s" outFile
             SimpleTemplating.UseFileAsSimpleTemplate(substitutions, templateOpt, outFile)
 
-        for info in model.EntityInfos do
+        for info in model.EntityInfos |> List.filter (fun info -> not info.Entity.Exclude) do
             let content = MarkdownDocument(entityContent info, Map.empty)
 
             let pageTitle = sprintf "%s (%s)" info.Entity.Name collectionName

src/FSharp.Formatting.ApiDocs/GenerateModel.fs

@@ -2261,12 +2261,30 @@ module internal SymbolReader =
             let sum = el.Element(XName.Get "summary")
 
             match sum with
-            | null when String.IsNullOrEmpty el.Value -> cmds, ApiDocComment.Empty, None
+
+            // sum can be null with null/empty el.Value when an non-"<summary>" XML element appears
+            // as the only '///' documentation command:
+            //
+            // 1.
+            //  // Not triple-slash ccomment
+            //  /// <exclude/>
+            //
+            // 2.
+            //  /// <exclude/>
+            //
+            // So, we need to let the 'null' case handle this to extract the <exclude> if it's there
+            //
+            // | null when String.IsNullOrEmpty el.Value ->
+            //     cmds, ApiDocComment.Empty, None
+
             | null ->
                 // We let through XML comments without a summary tag. It's not clear
                 // why as all XML coming through here should be from F# .XML files
                 // and should have the tag.  It may be legacy of previously processing un-processed
                 // XML in raw F# source.
+                //
+                // 9-Jan-23: See comment above for at least one reason why we pass through here now
+
                 let doc, nsels = readXmlCommentAsHtmlAux false ctx.UrlMap el cmds
 
                 let nsdocs = readNamespaceDocs ctx.UrlMap nsels
@@ -2275,6 +2293,12 @@ module internal SymbolReader =
                 if ctx.MarkdownComments then
                     readMarkdownCommentAndCommands ctx sum.Value el cmds
                 else
+                    if sum.Value.Contains("<exclude") then
+                        cmds.["exclude"] <- ""
+                        printfn
+                            "Warning: detected \"<exclude/>\" in text of \"<summary>\" for \"%s\". Please see https://fsprojects.github.io/FSharp.Formatting/apidocs.html#Classic-XML-Doc-Comments"
+                            xmlSig
+
                     readXmlCommentAndCommands ctx sum.Value el cmds
 
     /// Reads XML documentation comments and calls the specified function