[WIP] Experiment with porting generation to signature like API

.editorconfig

@@ -16,5 +16,21 @@ fsharp_max_array_or_list_width=120
 fsharp_max_infix_operator_expression=80
 fsharp_max_value_binding_width=120
 
-[GenerateHtml.fs]
-fsharp_experimental_elmish = true
+[{GenerateHtml.fs,tests/FSharp.ApiDocs.Tests/files/ReferenceProject/**/*.fs}]
+# Specific settings for "View/HTML" related files
+# It makes the code more consistent in term of spacing and indentation
+fsharp_experimental_elmish = true
+fsharp_array_or_list_multiline_formatter = number_of_items
+fsharp_max_array_or_list_number_of_items = 0
+
+# In general, the following settings are what I use for any F# project.
+# I didn't apply them globally yet because it will affect all the projects and I want to 
+# have confirmation from the team before doing so.
+fsharp_alternative_long_member_definitions = true
+fsharp_multi_line_lambda_closing_newline = true
+fsharp_multiline_bracket_style = aligned
+fsharp_keep_max_number_of_blank_lines = 1
+fsharp_align_function_signature_to_indentation = true
+fsharp_max_if_then_else_short_width = 0
+fsharp_max_record_number_of_items = 0 # Keep records consistent
+fsharp_record_multiline_formatter = number_of_items

FSharp.Formatting.sln

@@ -128,6 +128,14 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "content", "content", "{FAD5
 		docs\content\fsdocs-theme-set-dark.js = docs\content\fsdocs-theme-set-dark.js
 	EndProjectSection
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{DD76B368-3C5C-4E4A-B3B2-812E950BD497}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "FSharp.ApiDocs.Tests", "FSharp.ApiDocs.Tests", "{DE36A7E8-8F98-4763-B859-F452BCA9A675}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "files", "files", "{DFDABFED-63CB-46D1-B27D-BF674A820903}"
+EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "ReferenceProject", "tests\FSharp.ApiDocs.Tests\files\ReferenceProject\ReferenceProject.fsproj", "{CDDD197C-6F51-4BDC-A2C2-87622A784A72}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -230,6 +238,10 @@ Global
 		{CB78F0EA-8005-4735-A02C-B86CEDC29D85}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{CB78F0EA-8005-4735-A02C-B86CEDC29D85}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{CB78F0EA-8005-4735-A02C-B86CEDC29D85}.Release|Any CPU.Build.0 = Release|Any CPU
+		{CDDD197C-6F51-4BDC-A2C2-87622A784A72}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{CDDD197C-6F51-4BDC-A2C2-87622A784A72}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{CDDD197C-6F51-4BDC-A2C2-87622A784A72}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{CDDD197C-6F51-4BDC-A2C2-87622A784A72}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -265,6 +277,9 @@ Global
 		{188DC91F-2202-4495-ACD2-542D7C30364E} = {C7804F57-7FC6-4CF6-BDF6-127D6F9EBEA6}
 		{FAD5C374-4748-4A3D-A435-FFA425916F3A} = {312E452A-1068-4804-89E7-0AFBAD5F885F}
 		{52B949AA-A3F7-4894-B713-804BAEB71118} = {4AE0198D-EDE5-40B0-A5CD-FC7B6F891D94}
+		{DE36A7E8-8F98-4763-B859-F452BCA9A675} = {DD76B368-3C5C-4E4A-B3B2-812E950BD497}
+		{DFDABFED-63CB-46D1-B27D-BF674A820903} = {DE36A7E8-8F98-4763-B859-F452BCA9A675}
+		{CDDD197C-6F51-4BDC-A2C2-87622A784A72} = {DFDABFED-63CB-46D1-B27D-BF674A820903}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {76F121F8-70E0-49FB-9ADF-C7B660C0EB67}

build.fsx

@@ -93,4 +93,38 @@ pipeline "Verify" {
     runIfOnlySpecified true
 }
 
+let referenceProjectDir = "./tests/FSharp.ApiDocs.Tests/files/ReferenceProject"
+
+// TODO: Revisit to see how we can use `dotnet watch` to run a local version of the tool
+// against ReferenceProject
+// dotnet watch change the CWD and fsdocs-tool does not seems to allow changing the CWD
+pipeline "APIDocsReference" {
+
+    stage "Clean up" {
+        // Remove temporary files
+        run (fun _ ->
+            Shell.cleanDirs [
+                "./tests/FSharp.ApiDocs.Tests/files/ReferenceProject/.fsdocs"
+                "./tests/FSharp.ApiDocs.Tests/files/ReferenceProject/.tmp"
+                "./tests/FSharp.ApiDocs.Tests/files/ReferenceProject/.bin"
+                "./tests/FSharp.ApiDocs.Tests/files/ReferenceProject/.obj"
+            ]
+        )
+    }
+
+    stage "Build project"  {
+        // Make sure we have the required information for generating the API docs
+        workingDir referenceProjectDir
+        run "dotnet build"
+    }
+
+    stage "Generate API Docs" {
+        // Run a local version of the tool against the ReferenceProject
+        workingDir referenceProjectDir
+        run "dotnet run --project ../../../../src/fsdocs-tool -- watch --nolaunch --projects ReferenceProject.fsproj --sourcefolder ../../../../src/fsdocs-tool/../../tests/FSharp.ApiDocs.Tests/files/ReferenceProject"
+    }
+
+    runIfOnlySpecified
+}
+
 tryPrintPipelineCommandHelp ()

docs/_template.html

@@ -25,6 +25,16 @@
     <script type="application/javascript" src="{{root}}content/fsdocs-details-set-expanded.js"></script>
     <link href="{{root}}content/fsdocs-default.css" rel="stylesheet" type="text/css"/>
     <link href="{{root}}content/fsdocs-theme.css" rel="stylesheet" type="text/css"/>
+    <!-- Load prism.js -->
+    <!-- 
+        TODO:
+        We probably want to add the auto-loader plugin to make the initial prism.js as small as possible
+        This plugin allows to load language on demand, right now I loaded the most default languages from prism.js
+        and the ones supported by Fable.
+        markup+css+clike+javascript+dart+fsharp+python+rust
+    -->
+    <link href="{{root}}content/prism/prism.css" rel="stylesheet" type="text/css"/>
+    <script type="module" src="{{root}}content/prism/prism.js"></script>
     {{fsdocs-head-extra}}
     {{fsdocs-watch-script}}
 </head>

docs/content/fsdocs-default.css

@@ -122,6 +122,7 @@
     --code-preprocessor-color: #af75c1;
     --code-fsioutput-color: #808080;
     --code-tooltip-color: #d1d1d1;
+
 }
 
 /* dark theme */
@@ -671,7 +672,10 @@ a {
 
 p {
     line-height: 1.8;
-    margin-top: var(--spacing-300);
+
+    &:not(:last-child) {
+        margin-bottom: var(--spacing-300);
+    }
 }
 
 ol, ul {
@@ -713,23 +717,20 @@ blockquote {
 /* Code snippets */
 
 /* reset browser style */
-pre {
-    margin: 0;
-    padding: 0;
-}
+
 
 code, table.pre, pre {
     background-color: var(--code-background);
     color: var(--code-color);
-    font-family: var(--monospace-font);
+    font-family: var(--monospace-font); 
     font-variant-ligatures: none;
     font-size: var(--font-200);
     -webkit-text-size-adjust: 100%;
 }
 
 h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
     font-size: inherit;
-}
+}  
 
 table.pre, #content > pre.fssnip {
     border: 1px solid var(--code-fence-border-color);
@@ -1062,20 +1063,11 @@ span[onmouseout] {
                 flex-grow: 1;
             }
 
-            & pre {
-                margin-bottom: var(--spacing-200);
-                padding: var(--spacing-50);
-                flex-grow: 1;
-                overflow-x: auto;
-            }
         }
     }
 
     .fsdocs-summary-contents {
-        display: flex;
-        flex-direction: column;
-        justify-content: flex-start;
-        align-items: flex-start;
+        width: 100%;
     }
 
     .fsdocs-member-xmldoc-column {
@@ -1286,3 +1278,118 @@ dialog {
         opacity: 0.75;
     }
 }
+
+
+
+
+
+/* Code */
+
+.fsdocs-api-code {
+    font-family: var(--monospace-font);
+    margin-bottom: 1rem;
+
+    a.record-field-name,
+    a.union-case-property,
+    a.property {
+        /* color: darken($primary, 4%); */
+
+        &:hover {
+            text-decoration: underline;
+        }
+    }
+
+    .property[id]:target,
+    a[id]:target {
+        animation-name: blink;
+        animation-direction: normal;
+        animation-duration: 0.75s;
+        animation-iteration-count: 2;
+        animation-timing-function: ease;
+    }
+
+    span {
+        &.property {
+            color: var(--code-property-color);
+        }
+
+        &.keyword {
+            color: var(--code-keywords-color);
+        }
+
+        &.type {
+            color: var(--code-reference-color);
+        }
+    }
+
+}
+
+/* 
+    Animations for blinking the target of a link 
+
+    It makes it easier to see where the link is pointing to
+*/
+@keyframes blink {
+    0% {
+        background-color: var(--primary);
+        color: var(--background);
+    }
+    100% {
+        background-color: transparent;
+        color: var(--link-color);
+    }
+}
+
+.docs-example:not(:last-child) {
+    margin-bottom: var(--spacing-300);
+}
+
+/* 
+    If there is parameter right after this one, add some margin.
+
+    We don't want to do it for all of them, because the last one is followed by a `hr` which already adds spacing around it.
+*/
+.fsdocs-doc-parameter {
+    margin-bottom: var(--spacing-300);
+}
+
+/* 
+.button {
+    padding: .5rem .75rem;
+    color: var(--text-color);
+    cursor: pointer;
+    border-radius: var(--radius);
+
+    &:has(iconify-icon) {
+        display: flex;
+        justify-content: center;
+        align-items: center;
+    }
+
+    &:hover {
+        background-color: var(--shadow-color);
+    }
+} */
+
+.fsdocs-block {
+    position: relative;
+    padding: 1rem;
+
+    &:not(:first-child) {
+        border-top: 1px solid var(--shadow-color);
+    }
+
+    .actions-buttons {
+        /* Buttons are in the top right of the current block */
+        position: absolute;
+        top: 1rem;
+        right: 1rem;
+
+        /* Should be extract as an independant .buttons class when reworking the CSS */
+        display: flex;
+        gap: .25rem;
+        flex-wrap: wrap;
+        justify-content: flex-start;
+        align-items: center;
+    }
+}