### Install Fsdocs-tool Locally Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero Installs the `fsdocs-tool` as a local dependency for the project. This allows for controlled updates to the tool version. ```bash dotnet tool install --local fsdocs-tool ``` -------------------------------- ### Load Project Binary in FsDocs Script (F#) Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero Demonstrates how to load a project's binary into an FsDocs script for creating documentation examples. It uses '#r' to reference the DLL and 'open' to access the project's namespace. ```fsharp #r "../src/Project1/bin/Debug/net6.0/Project1.dll" open Project1 // Actual consumption of your project! let result = SomeType.SomeMethod("foo") ``` -------------------------------- ### View Fsdocs Commands Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero Displays the available commands and options for the `fsdocs` tool, useful for understanding its capabilities after installation. ```bash dotnet fsdocs --help ``` -------------------------------- ### GitHub Actions CI Workflow for FsDocs Build Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero A sample GitHub Actions workflow file that triggers on pull requests. It sets up .NET, restores tools, builds the solution, and then runs the FsDocs build command. ```yaml name: CI on: [pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup .NET Core uses: actions/setup-dotnet@v3 - name: Restore tools run: dotnet tool restore - name: Build run: dotnet build YourSolution.sln - name: Documentation run: dotnet fsdocs build ``` -------------------------------- ### GitHub Actions Workflow for Deploying Documentation Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero This YAML workflow automates the deployment of documentation to GitHub Pages. It checks out code, sets up .NET, restores tools, builds the project, generates documentation using 'dotnet fsdocs build', and uploads the output as an artifact for deployment. ```yaml name: Docs # Trigger this Action when new code is pushed to the main branch on: push: branches: - main # We need some permissions to publish to Github Pages permissions: contents: write pages: write id-token: write jobs: build: runs-on: ubuntu-latest steps: # Checkout the source code - uses: actions/checkout@v4 # Setup dotnet, please use a global.json to ensure the right SDK is used! - name: Setup .NET uses: actions/setup-dotnet@v3 # Restore the local tools - name: Restore tools run: dotnet tool restore # Build the code for the API documentation - name: Build code run: dotnet build -c Release YourSolution.sln # Generate the documentation files - name: Generate the documentation' run: dotnet fsdocs build --properties Configuration=Release # Upload the static files - name: Upload documentation uses: actions/upload-pages-artifact@v2 with: path: ./output # GitHub Actions recommends deploying in a separate job. deploy: runs-on: ubuntu-latest needs: build steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v2 ``` -------------------------------- ### Install and Run fsdocs Tool Source: https://fsprojects.github.io/FSharp.Formatting/commandline Instructions for installing the fsdocs dotnet tool and the basic command structure for running it. This is the entry point for using the command-line interface. ```bash dotnet tool install fsdocs-tool dotnet fsdocs [command] [options] ``` -------------------------------- ### Dependabot Configuration for NuGet and GitHub Actions Updates Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero Configuration file for Dependabot to automatically check for and create pull requests for updates to NuGet packages and GitHub Actions. It specifies the update interval for each package ecosystem. ```yaml version: 2 updates: # Update to newer version of GitHub Actions - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly" # Update to newer NuGet dependencies - package-ecosystem: "nuget" directory: "/" schedule: interval: "daily" ``` -------------------------------- ### Fsdocs Project Configuration for API Documentation Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero Details the requirements for FSharp projects to be included in API documentation generation by `fsdocs`. This includes setting the output type to library, ensuring a build is performed, excluding test projects, and enabling documentation file generation. ```xml library true false ``` -------------------------------- ### fsdocs-tool Local Installation and File Operations Source: https://fsprojects.github.io/FSharp.Formatting/upgrade Demonstrates installing the fsdocs-tool locally, managing NuGet tool manifests, and performing file system operations for project restructuring. ```bash dotnet tool install fsdocs-tool --local git add dotnet-tools.json git rm -fr docs/tools git mv docs/input/* docs git mv docs/files/* docs ``` -------------------------------- ### F# Programmatic API Docs Generation Setup Source: https://fsprojects.github.io/FSharp.Formatting/apidocs Demonstrates the setup required to programmatically generate library documentation using FSharp.Formatting.ApiDocs. It includes loading the necessary DLL and opening relevant namespaces. ```fsharp #r "FSharp.Formatting.ApiDocs.dll" open FSharp.Formatting.ApiDocs open System.IO ``` -------------------------------- ### Configure Project Properties with Directory.Build.props Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero This XML snippet shows how to configure MSBuild properties like RepositoryUrl, FsDocsLicenseLink, FsDocsReleaseNotesLink, and PackageProjectUrl in a Directory.Build.props file. These properties are crucial for generating correct links in documentation and for the build process. ```xml https://github.com/fsprojects/FSharp.AWS.DynamoDB https://github.com/fsprojects/FSharp.AWS.DynamoDB/blob/master/License.md https://github.com/fsprojects/FSharp.AWS.DynamoDB/blob/master/RELEASE_NOTES.md https://fsprojects.github.io/FSharp.AWS.DynamoDB ``` -------------------------------- ### Access ApiDocComment Examples Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidoccomment Retrieves a list of example sections from an ApiDocComment object. The examples are returned as a list of ApiDocHtml, representing the formatted HTML content of each example. ```F# this.Examples ``` -------------------------------- ### Install fsdocs-tool Source: https://fsprojects.github.io/FSharp.Formatting/upgrade Installs the fsdocs-tool globally using the .NET CLI. This is the first step in upgrading to fsdocs. ```bash dotnet new tool dotnet tool install fsdocs-tool ``` -------------------------------- ### Install and Build F# Documentation with fsdocs-tool Source: https://fsprojects.github.io/FSharp.Formatting/index This snippet shows how to install the fsdocs-tool using the .NET CLI and then build or watch for changes in your F# project's documentation. ```bash dotnet tool install fsdocs-tool dotnet fsdocs build dotnet fsdocs watch ``` -------------------------------- ### Watch for Documentation Changes Source: https://fsprojects.github.io/FSharp.Formatting/upgrade Starts a local development server that watches for changes in the documentation files and rebuilds the site automatically. ```bash dotnet fsdocs watch ``` -------------------------------- ### F# Formatting API Cross-Reference Examples Source: https://fsprojects.github.io/FSharp.Formatting/content Demonstrates how to use the 'cref:' syntax within Markdown to create cross-references to F# and .NET API documentation. These examples show how different signatures resolve to specific documentation links. ```markdown ``cref:T:FSharp.Formatting.Markdown.MarkdownParagraph`` ``` ```markdown ``cref:T:System.Console`` ``` ```markdown ``cref:M:System.Console.WriteLine`` ``` ```markdown ``cref:M:System.Console.WriteLine(System.String)`` ``` ```markdown ```cref:T:FSharp.Control.FSharpAsync`1``` ``` -------------------------------- ### FSharp.Formatting CLI Usage Source: https://fsprojects.github.io/FSharp.Formatting/commandline Installs and runs the fsdocs dotnet tool for generating documentation. ```APIDOC ## Install and Use fsdocs CLI ### Description Installs the fsdocs dotnet tool and provides basic usage instructions. ### Method CLI Command ### Endpoint N/A ### Parameters None ### Request Example ```bash dotnet tool install fsdocs-tool dotnet fsdocs [command] [options] ``` ### Response N/A ``` -------------------------------- ### Moving F# Code Definitions with Include/Define Source: https://fsprojects.github.io/FSharp.Formatting/sidebyside/sidescript Illustrates using 'include' and 'define' commands in F# Formatting to manage code execution order, allowing code to be explained before its definition appears in the script. ```fsharp let sample = laterFunction () |> printfn "Got: %s" ``` ```fsharp let laterFunction () = "Not very difficult, is it?" ``` -------------------------------- ### Markdown Link Translation Example Source: https://fsprojects.github.io/FSharp.Formatting/content Shows how a markdown link to a local file (e.g., 'some-file.md') is automatically translated to a link to its corresponding HTML output file ('some-file.html') during the documentation build process. ```markdown [Some Text](some-file.md) ``` -------------------------------- ### Basic F# Function: Factorial Source: https://fsprojects.github.io/FSharp.Formatting/sidebyside/sidescript Defines a recursive factorial function in F#. This is a common example demonstrating basic F# syntax and recursion. ```fsharp /// The Hello World of functional languages! let rec factorial x = if x = 0 then 1 else x * (factorial (x - 1)) let f10 = factorial 10 ``` -------------------------------- ### Programmatic API Documentation Generation Source: https://fsprojects.github.io/FSharp.Formatting/apidocs Provides instructions and code examples for generating API documentation programmatically using the `ApiDocs` type from the `FSharp.Formatting.ApiDocs` library. This includes loading assemblies and using methods like `GenerateHtml`. ```APIDOC ## Building library documentation programmatically ### Description This section explains how to programmatically generate library documentation using the `ApiDocs` functionality. It covers loading assemblies, specifying input files, and configuring output options for HTML generation. ### Method N/A (Library Functionality) ### Endpoint N/A ### Parameters None ### Request Example ```fsharp #r "FSharp.Formatting.ApiDocs.dll" open FSharp.Formatting.ApiDocs open System.IO let file = Path.Combine(root, "bin/YourLibrary.dll") let input = ApiDocInput.FromFile(file) ApiDocs.GenerateHtml( [ input ], output = Path.Combine(root, "output"), collectionName = "YourLibrary", template = Path.Combine(root, "templates", "template.html"), substitutions = [] ) ``` ### Response None #### Success Response (N/A) N/A #### Response Example None ``` -------------------------------- ### F# Script Front Matter Example Source: https://fsprojects.github.io/FSharp.Formatting/content Illustrates the front matter format specific to F# scripts, using a similar YAML structure enclosed in F# comment syntax for metadata. ```fsharp (* --- title: A Literate Script category: Examples categoryindex: 2 index: 1 description: Some description keywords: tag1, tag2, tag3 --- *) ``` -------------------------------- ### F# API Docs Generation using GenerateHtml Source: https://fsprojects.github.io/FSharp.Formatting/apidocs Provides an example of using the `ApiDocs.GenerateHtml` method to create HTML documentation from a compiled F# assembly. It specifies input assembly, output directory, collection name, and template. ```fsharp let file = Path.Combine(root, "bin/YourLibrary.dll") let input = ApiDocInput.FromFile(file) ApiDocs.GenerateHtml( [ input ], output = Path.Combine(root, "output"), collectionName = "YourLibrary", template = Path.Combine(root, "templates", "template.html"), substitutions = [] ) ``` -------------------------------- ### Set FsDocs Styling Parameters in Project File Source: https://fsprojects.github.io/FSharp.Formatting/styling This example demonstrates how to configure various FsDocs styling and generation parameters within a .NET project file (e.g., .fsproj). These parameters control aspects like logo, favicon, license links, and warning behavior, affecting the final generated documentation site. ```xml https://github.com/foo/bar/blob/master/License.txt https://foo.github.io/bar/ https://github.com/foo/bar/ https://fsharp.org img/logo.png img/favicon.ico https://github.com/foo/bar/blob/master/License.txt https://github.com/foo/bar/blob/master/release-notes.md true default ``` -------------------------------- ### F# Code Snippet Example Source: https://fsprojects.github.io/FSharp.Formatting/sidebyside/sidemarkdown Demonstrates embedding a standard F# code snippet within Markdown. This code is processed and formatted by FSharp.Formatting. ```fsharp /// The Hello World of functional languages!\ let rec factorial x = if x = 0 then 1 else x * (factorial (x - 1)) let f10 = factorial 10 ``` -------------------------------- ### Markdown Front Matter Example Source: https://fsprojects.github.io/FSharp.Formatting/content Demonstrates the YAML front matter format used in markdown files to define metadata for documentation generation, including title, category, and keywords. ```markdown --- title: Some Title category: Some Category categoryindex: 2 index: 3 description: Some description keywords: tag1, tag2, tag3 --- ``` -------------------------------- ### F# Function with XML Docs Source: https://fsprojects.github.io/FSharp.Formatting/apidocs Defines a simple F# function `someFunction` and its associated XML documentation comments, including summary, parameter, return, example, and category tags. ```fsharp /// Another paragraph, see . /// /// /// The input /// /// The output /// /// /// Try using /// /// open TheNamespace /// SomeModule.a /// /// /// /// Foo /// let someFunction x = 42 + x ``` -------------------------------- ### Create ApiDocComment Object Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidoccomment Constructs an ApiDocComment object by providing various documentation parts such as xmldoc, summary, remarks, parameters, returns, examples, notes, exceptions, and raw data. This constructor is essential for programmatically creating documentation comment representations. ```F# ApiDocComment(xmldoc, summary, remarks, parameters, returns, examples, notes, exceptions, rawData) ``` -------------------------------- ### CommentRegEx Property - FSharp.Formatting Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-mshformat Gets the regular expression string used to match single-line comments starting with '#'. This property is abstract and must be implemented by derived classes. ```F# this.CommentRegEx : string ``` -------------------------------- ### Ignore Generated Files in .gitignore Source: https://fsprojects.github.io/FSharp.Formatting/zero-to-hero This .gitignore content specifies directories and files that should be ignored by Git, including .fsdocs cache, generated documentation output, and temporary files. This prevents unnecessary files from being committed to the repository. ```gitignore # FSharp.Formatting .fsdocs/ output/ tmp/ ``` -------------------------------- ### F# XML Documentation Comment Example with NamespaceDoc Source: https://fsprojects.github.io/FSharp.Formatting/apidocs This F# code snippet illustrates the use of XML documentation comments, including the `summary`, `remarks`, and `namespacedoc` tags. The `namespacedoc` tag is specifically used to provide documentation for the entire namespace. ```fsharp /// /// A module /// /// /// /// A namespace to remember /// /// More on that /// /// /// /// Some actual comment ``` -------------------------------- ### Generating iPython Notebook Output with FSharp.Formatting Source: https://fsprojects.github.io/FSharp.Formatting/content Describes how to generate iPython Notebook (.ipynb) output using an optional `_template.ipynb` file. It also shows how to include a mybinder badge for interactive notebook execution by referencing a `Dockerfile` and `NuGet.config`. ```markdown [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/fsprojects/FSharp.Formatting/gh-pages?filepath=literate.ipynb) ``` -------------------------------- ### F# code snippet with multiple samples and HTML structure Source: https://fsprojects.github.io/FSharp.Formatting/codeformat Illustrates an F# code snippet formatted with HTML, including line numbers and spans for different code elements (comments, identifiers, strings, numbers). This example shows how the F# Formatting library handles multiple snippets separated by `// [snippet: ...]` comments, producing distinct HTML blocks for each snippet and shared tooltips. ```html 
1: 
2: 
3: 
4: 
5: 
6: 
7: 

// [snippet: First sample]
printf "The answer is: %A" 42
// [/snippet]
// [snippet: Second sample]
printf "Hello world!"
// [/snippet]
``` -------------------------------- ### Get CSS Stylesheet as Stream - F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-sourceformat Gets the CSS stylesheet as a stream. This stream contains the definitions for CSS classes used by CSharpFormat for syntax highlighting, allowing it to be embedded or linked in web pages. ```F# let getCssStream () : System.IO.Stream = FSharp.Formatting.CSharpFormat.SourceFormat.GetCssStream() ``` -------------------------------- ### Searchable Docs Implementation Source: https://fsprojects.github.io/FSharp.Formatting/commandline Details on how to implement search functionality in your documentation using the generated index.json and provided scripts. ```APIDOC ## Searchable Docs ### Description When using the command-line tool, a Fuse search index is automatically generated in `index.json`. A search box is included in the default template. To add search to your own `_template.html`, you need to include specific HTML elements and a JavaScript file. ### Method HTML/JavaScript Integration ### Endpoint N/A ### Parameters None ### Request Example ```html

    Type something to start searching.

     ``` ### Response Enables a search interface within the documentation, allowing users to search through content indexed in `index.json`. ``` -------------------------------- ### Get CSS Stylesheet as String - F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-sourceformat Gets the CSS stylesheet as a string. This string contains the definitions for CSS classes used by CSharpFormat for syntax highlighting, making it easy to include directly in HTML or CSS files. ```F# let getCssString () : string = FSharp.Formatting.CSharpFormat.SourceFormat.GetCssString() ``` -------------------------------- ### Getting Member Name in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember Retrieves the name of an F# member. This is the identifier used to refer to the member within the code. ```F# this.Name ``` -------------------------------- ### Get Snippets Property (F#) Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-codeformat-formattedcontent Retrieves the processed snippets as an array from a FormattedContent object. This is an instance member of the FormattedContent type. ```F# let snippetsArray = formattedContent.Snippets ``` -------------------------------- ### fsdocs build command Source: https://fsprojects.github.io/FSharp.Formatting/commandline Processes a 'docs' directory to generate API documentation for projects in a solution. ```APIDOC ## fsdocs build ### Description Processes a `docs` directory and generates API docs for projects in the solution. It follows specific rules for API doc generation. The command accepts various options to customize the build process. ### Method CLI Command ### Endpoint N/A ### Parameters #### Command Line Options * `--input` (string) - Input directory of content (default: `docs`) * `--projects` (string) - Project files to build API docs for outputs, defaults to all packable projects. * `--output` (string) - Output Directory (default 'output' for 'build' and 'tmp/watch' for 'watch'). * `--ignoreuncategorized` - Disable generation of the 'Other' category in the navigation bar for uncategorized docs. * `--noapidocs` - Disable generation of API docs. * `--ignoreprojects` - Disable project cracking. * `--eval` - Evaluate F# fragments in scripts. * `--saveimages` - Save images referenced in docs. * `--nolinenumbers` - Don't add line numbers (default is to add line numbers). * `--parameters` (string) - Additional substitution parameters for templates. * `--nonpublic` - The tool will also generate documentation for non-public members. * `--nodefaultcontent` - Do not copy default content styles, javascript or use default templates. * `--clean` - Clean the output directory. * `--help` - Display this help screen. * `--version` - Display version information. * `--properties` (string) - Provide properties to dotnet msbuild, e.g. `--properties Configuration=Release Version=3.4`. * `--fscoptions` (string) - Additional arguments passed down as `otherflags` to the F# compiler when the API is being generated. Example: `--fscoptions " -r:MyAssembly.dll"`. * `--strict` - Fail if docs are missing or can't be generated. #### Recommended Project File Settings (Alternative to CLI options) * `--sourceFolder` (string) - Source folder at time of component build (``) * `--sourceRepo` (string) - Source repository for github links (``) * `--mdComments` - Assume comments in F# code are markdown (``) ### Request Example ```bash fsdocs build ``` ### Response Reports on `.fsproj` files, indicating if they are skipped and why (e.g., project name contains '.Tests' or 'test', or missing `true` in the `.fsproj` file). ``` -------------------------------- ### F# ApiDocNamespace Name Property Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocnamespace Gets the name of the namespace. This is a simple string property representing the identifier for the namespace. ```fsharp this.Name : string ``` -------------------------------- ### Generate HTML Documentation (F#) Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocs Generates default HTML pages for specified assemblies. It takes input components, an output directory, collection name, substitutions, and optional parameters for templates, root URLs, qualification, library directories, compiler flags, and error handling. ```F# ApiDocs.GenerateHtml( inputs: ApiDocInput list, output: string, collectionName: string, substitutions: Substitutions, ?template: string, ?root: string, ?qualify: bool, ?libDirs: string list, ?otherFlags: string list, ?urlRangeHighlight: Uri -> int -> int -> string, ?onError: string -> unit ) : ApiDocModel * ApiDocsSearchIndexEntry[] ``` -------------------------------- ### FSharp.Formatting fsdocs-release-notes-link ParamKey Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-templating-paramkeys Parameter key for the release notes link in FSharp.Formatting. It provides a direct link to the release notes of a package. ```F# ParamKeys.fsdocs-release-notes-link ``` -------------------------------- ### HtmlText Property (F#) Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidochtml Gets the HTML text content of the ApiDocHtml object. This property returns the raw HTML string. ```fsharp this.HtmlText : string ``` -------------------------------- ### ApiDocCollection CollectionName Property (F#) Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidoccollection Gets the name of the ApiDocCollection. This property returns a string representing the collection's name. ```fsharp this.CollectionName : string ``` -------------------------------- ### FormattedSnippet Constructor Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-codeformat-formattedsnippet Initializes a new instance of the FormattedSnippet class with a key and content. ```APIDOC ## FormattedSnippet Constructor ### Description Initializes a new instance of the FormattedSnippet class. ### Method Constructor ### Parameters #### Parameters - **key** (string) - Description of the key parameter - **content** (string) - Description of the content parameter ### Request Example ```json { "key": "exampleKey", "content": "exampleContent" } ``` ### Response #### Success Response (200) - **FormattedSnippet** (object) - An instance of the FormattedSnippet class. ``` -------------------------------- ### FSharp.Formatting LiterateDocument Constructor Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-literate-literatedocument Constructs a new LiterateDocument. It requires parameters for paragraphs, formatted tips, links, source, source file, root input folder, and diagnostics. ```F# LiterateDocument(paragraphs: MarkdownParagraphs, formattedTips: string, links: IDictionary, source: LiterateSource, sourceFile: string, rootInputFolder: string option, diagnostics: SourceError array) ``` -------------------------------- ### JavaScriptFormat.Preprocessors Property (F#) Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-javascriptformat Retrieves the definition for preprocessor directives in JavaScript. This abstract property is used to color-code directives starting with '@'. ```fsharp let preprocessors = formatter.Preprocessors ``` -------------------------------- ### F# Module and Type Definitions with Documentation Source: https://fsprojects.github.io/FSharp.Formatting/apidocs Illustrates defining F# modules and types with associated documentation comments. It shows how to document types, modules, and functions, including how references to types like `Foo.Bar` and `Foo.Baz` are handled. ```fsharp /// Contains two types [Bar] and [Foo.Baz] module Foo = /// Bar is just an `int` and belongs to module [Foo] type Bar = int /// Baz contains a `Foo.Bar` as its `id` type Baz = { id: Bar } /// This function operates on `Baz` types. let f (b: Baz) = b.id * 42 /// Referencing [Foo3] will not generate a link as there is no type with the name `Foo3` module Foo3 = /// This is not the same type as `Foo.Bar` type Bar = double /// Using the simple name for [Bar] will fail to create a link because the name is duplicated in /// [Foo.Bar] and in [Foo3.Bar]. In this case, using the full name works. let f2 b = b * 50 ``` -------------------------------- ### Getting Member Symbol in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember Retrieves the FSharpSymbol associated with a member. This provides a programmatic handle to the member's underlying representation. ```F# this.Symbol ``` -------------------------------- ### Retrieving Member Comments in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember Gets the associated comment for an F# member. This is valuable for documentation generation or displaying help text. ```F# this.Comment ``` -------------------------------- ### SyntaxHighlighter Constructors Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-syntaxhighlighter Provides constructors for initializing the SyntaxHighlighter class. ```APIDOC ## SyntaxHighlighter() ### Description Initializes a new instance of the SyntaxHighlighter class. ### Method CONSTRUCTOR ### Endpoint N/A ### Parameters None ### Request Example ```csharp var highlighter = new SyntaxHighlighter(); ``` ### Response #### Success Response (200) N/A (Constructor) #### Response Example N/A (Constructor) ``` -------------------------------- ### Getting Member Category in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember Retrieves the category of an F# member. This can be used for organizing or filtering members based on their type or purpose. ```F# this.Category ``` -------------------------------- ### Rebase Documentation Links using CLI (Text) Source: https://fsprojects.github.io/FSharp.Formatting/apidocs Demonstrates how to set the base URL for links in the generated documentation using the `dotnet fsdocs build` command with the `--parameters root` option. This is useful for local testing or when the documentation is hosted at a different base path than the default. ```text dotnet fsdocs build --output public/docs --parameters root ../ ``` -------------------------------- ### Get Length of TokenSpan List in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-codeformat-tokenspans Returns the total number of TokenSpan elements in the list. This property returns an integer. ```fsharp this.Length ``` -------------------------------- ### Generate HTML Documentation Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocs Generates default HTML pages for the assemblies specified by the inputs parameter. ```APIDOC ## ApiDocs.GenerateHtml ### Description Generates default HTML pages for the assemblies specified by the `inputs` parameter. ### Method GET (or POST, depending on implementation context) ### Endpoint /websites/fsprojects_github_io/fsharp_formatting/ApiDocs/GenerateHtml ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **inputs** (ApiDocInput list) - Required - the components to generate documentation for - **output** (string) - Required - the output directory - **collectionName** (string) - Required - the overall collection name - **substitutions** (Substitutions) - Required - the substitutions to use in content and templates - **template** (string) - Optional - the template to use for each documentation page - **root** (string) - Optional - The root url of the generated documentation within the website - **qualify** (bool) - Optional - qualify the output set by collection name, e.g. `reference/FSharp.Core/...` - **libDirs** (string list) - Optional - Use this to specify additional paths where referenced DLL files can be found when formatting code snippets inside Markdown comments - **otherFlags** (string list) - Optional - Additional flags that are passed to the F# compiler to specify references explicitly etc. - **urlRangeHighlight** (Uri -> int -> int -> string) - Optional - A function that can be used to override the default way of generating GitHub links - **onError** (string -> unit) - Optional ### Request Example ```json { "inputs": [ { "projectFile": "path/to/your/project.fsproj", "dependencies": [] } ], "output": "./docs", "collectionName": "MyProject", "substitutions": { "Version": "1.0.0" }, "template": "./templates/default.liquid" } ``` ### Response #### Success Response (200) - **apiDocModel** (ApiDocModel) - The generated API documentation model. - **searchIndexEntries** (ApiDocsSearchIndexEntry[]) - The search index entries. #### Response Example ```json { "apiDocModel": { ... }, "searchIndexEntries": [ { ... }, { ... } ] } ``` ``` -------------------------------- ### Get F# Checker Instance Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-codeformat-codeformatter Returns an instance of the FSharpChecker, which is likely used for interacting with the F# compiler services to perform analysis. ```F# fsChecker () : FSharpChecker ``` -------------------------------- ### VisualBasicFormat Preprocessors Property Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-visualbasicformat Gets the list of Visual Basic preprocessor directives. This property aids in the correct parsing and formatting of preprocessor statements. ```fsharp let vbPreprocessors = visualBasicFormatter.Preprocessors ``` -------------------------------- ### Getting Member Return Information in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember Retrieves information about the return value of an F# member, typically used in tooltips or documentation summaries. ```F# this.ReturnInfo ``` -------------------------------- ### Specify project information for template replacement Source: https://fsprojects.github.io/FSharp.Formatting/literate Demonstrates how to load a template file and provide project-specific information as parameters for replacement within the template. This is useful for customizing generated documentation. ```fsharp // Load the template & specify project information let projTemplate = source + "template-project.html" let projInfo = [ "fsdocs-authors", "Tomas Petricek" "fsdocs-source-link", "https://github.com/fsprojects/FSharp.Formatting" "fsdocs-collection-name", "F# Formatting" ] ``` -------------------------------- ### Retrieving Obsolete Message in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember Gets the message associated with an obsolete F# member. If the member is not obsolete or has no message, an empty string is returned. ```F# this.ObsoleteMessage ``` -------------------------------- ### Create fsdocs Template Files Source: https://fsprojects.github.io/FSharp.Formatting/upgrade Creates template files for F# scripts and notebooks, which can be used by fsdocs for co-generation. Also adds these files to Git version control. ```bash touch docs/_template.fsx touch docs/_template.ipynb git add docs/_template.fsx git add docs/_template.ipynb ``` -------------------------------- ### Preprocessors Property - FSharp.Formatting Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-mshformat Gets the regular expression string used to highlight operators, often used for preprocessor directives. This property is abstract. ```F# this.Preprocessors : string ``` -------------------------------- ### Generate Markdown Documentation (F#) Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocs Generates default Markdown pages for specified assemblies. It accepts input components, an output directory, collection name, substitutions, and optional parameters for templates, root URLs, qualification, library directories, compiler flags, and error handling. ```F# ApiDocs.GenerateMarkdown( inputs: ApiDocInput list, output: string, collectionName: string, substitutions: Substitutions, ?template: string, ?root: string, ?qualify: bool, ?libDirs: string list, ?otherFlags: string list, ?urlRangeHighlight: Uri -> int -> int -> string, ?onError: string -> unit ) : ApiDocModel * ApiDocsSearchIndexEntry[] ``` -------------------------------- ### FsiEvaluatorConfig Constructors Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-literate-evaluation-fsievaluatorconfig Details on how to create instances of the FsiEvaluatorConfig type. ```APIDOC ## Constructor FsiEvaluatorConfig ### Description Initializes a new instance of the `FsiEvaluatorConfig` class. ### Method CONSTRUCTOR ### Endpoint N/A ### Parameters None ### Request Example ```fsharp let config = FsiEvaluatorConfig() ``` ### Response #### Success Response (200) Returns an instance of `FsiEvaluatorConfig`. ### Response Example ```fsharp val config : FsiEvaluatorConfig ``` ``` -------------------------------- ### Keywords Property - FSharp.Formatting Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-mshformat Gets the list of MSH keywords. This property is abstract and intended to be overridden to provide the specific keywords for MSH syntax highlighting. ```F# this.Keywords : string ``` -------------------------------- ### Integrate Search into HTML Template Source: https://fsprojects.github.io/FSharp.Formatting/commandline Provides HTML and JavaScript snippets required to add a search functionality to custom documentation templates. This includes defining search input, display areas, and including the necessary script. ```html

      Type something to start searching.

       ``` -------------------------------- ### Get ToolTip Property (F#) Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-codeformat-formattedcontent Retrieves a string containing ToolTip elements for all snippets within a FormattedContent object. This is an instance member of the FormattedContent type. ```F# let toolTipString = formattedContent.ToolTip ``` -------------------------------- ### Generate Markdown Documentation Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocs Generates default Markdown pages for the assemblies specified by the inputs parameter. ```APIDOC ## ApiDocs.GenerateMarkdown ### Description Generates default Markdown pages for the assemblies specified by the `inputs` parameter. ### Method GET (or POST, depending on implementation context) ### Endpoint /websites/fsprojects_github_io/fsharp_formatting/ApiDocs/GenerateMarkdown ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **inputs** (ApiDocInput list) - Required - the components to generate documentation for - **output** (string) - Required - the output directory - **collectionName** (string) - Required - the overall collection name - **substitutions** (Substitutions) - Required - the substitutions to use in content and templates - **template** (string) - Optional - the template to use for each documentation page - **root** (string) - Optional - The root url of the generated documentation within the website - **qualify** (bool) - Optional - qualify the output set by collection name, e.g. `reference/FSharp.Core/...` - **libDirs** (string list) - Optional - Use this to specify additional paths where referenced DLL files can be found when formatting code snippets inside Markdown comments - **otherFlags** (string list) - Optional - Additional flags that are passed to the F# compiler to specify references explicitly etc. - **urlRangeHighlight** (Uri -> int -> int -> string) - Optional - A function that can be used to override the default way of generating GitHub links - **onError** (string -> unit) - Optional ### Request Example ```json { "inputs": [ { "projectFile": "path/to/your/project.fsproj", "dependencies": [] } ], "output": "./docs_md", "collectionName": "MyProject", "substitutions": { "Version": "1.0.0" }, "template": "./templates/markdown.liquid" } ``` ### Response #### Success Response (200) - **apiDocModel** (ApiDocModel) - The generated API documentation model. - **searchIndexEntries** (ApiDocsSearchIndexEntry[]) - The search index entries. #### Response Example ```json { "apiDocModel": { ... }, "searchIndexEntries": [ { ... }, { ... } ] } ``` ``` -------------------------------- ### HaskellFormat Constructor Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-haskellformat Initializes a new instance of the HaskellFormat class. ```APIDOC ## HaskellFormat Constructor ### Description Initializes a new instance of the HaskellFormat class. ### Method Constructor ### Endpoint N/A ### Parameters None ### Request Example ``` new HaskellFormat() ``` ### Response #### Success Response (200) N/A #### Response Example N/A ``` -------------------------------- ### Access Defined Links in MarkdownDocument (F#) Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-markdown-markdowndocument Illustrates how to get the dictionary of explicitly defined links within a MarkdownDocument. This is useful for managing or inspecting hyperlink references. ```F# let definedLinks = markdownDoc.DefinedLinks ``` -------------------------------- ### Retrieving Member Type Arguments in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember Gets a list of type arguments for a generic F# member. This is essential for understanding the generic constraints and types used. ```F# this.TypeArguments ``` -------------------------------- ### Substitutions Type Members Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-templating-substitutions Documentation for the instance and static members of the Substitutions type. ```APIDOC ## Substitutions Type ### Description A list of parameters for substituting in templates, indexed by parameter keys. ### Namespace FSharp.Formatting.Templating ### Assembly FSharp.Formatting.Common.dll ### Instance Members #### `this.Head` ##### Description Returns the first parameter in the substitutions list. ##### Returns `ParamKey * string` #### `this.IsEmpty` ##### Description Checks if the substitutions list is empty. ##### Returns `bool` #### `this[index]` ##### Description Retrieves a parameter at a specific index in the substitutions list. ##### Parameters - **index** (`int`) - The index of the parameter to retrieve. ##### Returns `ParamKey * string` #### `this.Length` ##### Description Returns the number of parameters in the substitutions list. ##### Returns `int` #### `this.Tail` ##### Description Returns the rest of the parameters in the substitutions list, excluding the first one. ##### Returns `(ParamKey * string) list` ### Static Members #### `List.Empty` ##### Description Returns an empty substitutions list. ##### Returns `(ParamKey * string) list` ``` -------------------------------- ### FSharp.Formatting fsdocs-theme ParamKey Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-templating-paramkeys Parameter key for the theme in FSharp.Formatting. It specifies the documentation theme being used. ```F# ParamKeys.fsdocs-theme ``` -------------------------------- ### Getting Custom Operation Name in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember Retrieves the custom operation name for an F# member, specifically when it's associated with the CustomOperationAttribute. Returns None if not applicable. ```F# this.CustomOperationName ``` -------------------------------- ### F# Module with Cross-references using Source: https://fsprojects.github.io/FSharp.Formatting/apidocs Demonstrates using the `` tag within XML documentation comments in an F# module to create cross-references between functions. ```fsharp module Forest = /// /// Find at most limit foxes in current forest /// /// See also: /// let findFoxes (limit : int) = [] /// /// Find at most limit squirrels in current forest /// /// See also: /// let findSquirrels (limit : int) = [] ``` -------------------------------- ### Id Property (F#) Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidochtml Gets the optional ID of the ApiDocHtml object when rendered to HTML. This property returns an Option type which may contain a string value. ```fsharp this.Id : string option ``` -------------------------------- ### Getting Member URL Base Name in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember Retrieves the base name for generating documentation URLs for an F# item. This is the part of the URL without the base path. ```F# this.UrlBaseName ``` -------------------------------- ### Generate F# Documentation Model Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocs Generates a documentation model from specified inputs. It handles collection name, substitutions, and optional parameters like qualification, library directories, compiler flags, root URL, URL range highlighting, error handling, and file extensions. ```F# ApiDocs.GenerateModel(inputs, collectionName, substitutions, ?qualify, ?libDirs, ?otherFlags, ?root, ?urlRangeHighlight, ?onError, ?extension) ``` -------------------------------- ### Retrieving Member Modifiers in F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-apidocs-apidocmember Gets a list of modifiers applied to an F# member, such as 'public', 'private', 'static', etc. These define the member's accessibility and behavior. ```F# this.Modifiers ``` -------------------------------- ### Get Last Write Times F# Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-common-menu Retrieves the last modification times for files within a given input path. Returns a list of DateTime objects. ```fsharp getLastWriteTimes input ``` -------------------------------- ### FSharp.Formatting fsdocs-repository-link ParamKey Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-templating-paramkeys Parameter key for the repository link in FSharp.Formatting. It provides the URL to the source code repository. ```F# ParamKeys.fsdocs-repository-link ``` -------------------------------- ### StringRegEx Property - FSharp.Formatting Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-csharpformat-mshformat Gets the regular expression string used to match string and character literals. This abstract property defines the pattern for recognizing literal values. ```F# this.StringRegEx : string ``` -------------------------------- ### Configure FAKE for Documentation Generation Source: https://fsprojects.github.io/FSharp.Formatting/upgrade Adjusts the build.fsx file to include targets for generating and releasing documentation using fsdocs and Git. ```fsharp Target.create "GenerateDocs" (fun _ -> Shell.cleanDir ".fsdocs" DotNet.exec id "fsdocs" "build --clean" |> ignore ) Target.create "ReleaseDocs" (fun _ -> Git.Repository.clone "" projectRepo "temp/gh-pages" Git.Branches.checkoutBranch "temp/gh-pages" "gh-pages" Shell.copyRecursive "output" "temp/gh-pages" true |> printfn "%A" Git.CommandHelper.runSimpleGitCommand "temp/gh-pages" "add ." |> printfn "%s" let cmd = sprintf "commit -a -m \"Update generated documentation for version %s\"" release.NugetVersion Git.CommandHelper.runSimpleGitCommand "temp/gh-pages" cmd |> printfn "%s" Git.Branches.push "temp/gh-pages" ) ``` -------------------------------- ### FSharp.Formatting fsdocs-source ParamKey Source: https://fsprojects.github.io/FSharp.Formatting/reference/fsharp-formatting-templating-paramkeys Parameter key for the source in FSharp.Formatting. It provides general information about the source of the documentation page. ```F# ParamKeys.fsdocs-source ```