From 536565f2cad858491a7cfc52bc7283b968cabf4e Mon Sep 17 00:00:00 2001 From: Tuomas Hietanen Date: Sat, 2 Nov 2024 13:52:44 +0000 Subject: [PATCH] Update docs --- docs/apidocs.fsx | 22 +++++++++++----------- docs/codeformat.fsx | 10 +++++----- docs/commandline.md | 2 +- docs/content.fsx | 12 ++++++------ docs/evaluation.fsx | 16 ++++++++-------- docs/literate.fsx | 12 ++++++------ docs/markdown.fsx | 6 +++--- docs/sidebyside/sideextensions.md | 4 ++-- docs/sidebyside/sidemarkdown.md | 8 ++++---- docs/sidebyside/sidescript.fsx | 12 ++++++------ docs/styling.md | 10 +++++----- docs/zero-to-hero.md | 8 ++++---- 12 files changed, 61 insertions(+), 61 deletions(-) diff --git a/docs/apidocs.fsx b/docs/apidocs.fsx index c974205a7..aa814f4b4 100644 --- a/docs/apidocs.fsx +++ b/docs/apidocs.fsx @@ -61,7 +61,7 @@ The HTML is built by instantiating a template. The template used is the first of * The default template -Usually the same template can be used as for [other content](content.html). +Usually, the same template can be used as for [other content](content.html). ## Classic XML Doc Comments @@ -94,7 +94,7 @@ In addition, you may also use the [Recommended XML doc extensions for F# documen * `\(...\)` for inline math and `$$...$$` and `\[...\]`for math environments, see http://docs.mathjax.org. Some escaping of characters (e.g. `<`, `>`) may be needed to form valid XML -An example of an XML documentation comment, assuming the code is in namespace `TheNamespace`: +An example of an XML documentation comment, assuming the code is in the namespace `TheNamespace`: *) /// /// A module @@ -211,7 +211,7 @@ If the member cannot be found, a link to the containing module/type will be used (** ### 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 `` tag. +If you want to exclude modules or functions from the API docs, you can use the `` 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 `` (for example, you may wish to hide existing documentation while it's in progress). The `` tag can be the first or last line in these cases. @@ -304,7 +304,7 @@ You can do this in two different ways: * Add a [markdown inline link](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#links) were the link title is the name of the type you want to link. - /// this will generate a link to [Foo.Bar] documentation + /// This will generate a link to [Foo.Bar] documentation * Add a [Markdown inline code](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) (using back-ticks) where the code is the name of the type you want to link. @@ -312,8 +312,8 @@ back-ticks) where the code is the name of the type you want to link. /// This will also generate a link to `Foo.Bar` documentation You can use either the full name (including namespace and module) or the simple name of a type. -If more than one type is found with the same name the link will not be generated. -If a type with the given name is not found in the same assembly the link will not be generated. +If more than one type is found with the same name, the link will not be generated. +If a type with the given name is not found in the same assembly, the link will not be generated. *) /// Contains two types [Bar] and [Foo.Baz] @@ -353,7 +353,7 @@ module Bar = let a = 42 (** -Example as first line: +Example as the first line: *) /// [omit] @@ -366,8 +366,8 @@ module Bar2 = ## Building library documentation programmatically -You can build library documentation programatically using the functionality -in the `cref:T:FSharp.Formatting.ApiDocs.ApiDocs` type. To do this, load the assembly and open necessary namespaces: +You can build library documentation programmatically using the functionality +in the `cref:T:FSharp.Formatting.ApiDocs.ApiDocs` type. To do this, load the assembly and open the necessary namespaces: *) #r "FSharp.Formatting.ApiDocs.dll" @@ -414,7 +414,7 @@ ApiDocs.GenerateHtml( (** or use `libDirs` to include all assemblies from an entire folder. Tip: A combination of `true` in the fsproj file and setting `libDirs` to the compilation output path leads to only one folder with all dependencies referenced. -This might be easier especially for large projects with many dependencies. +This might be easier, especially for large projects with many dependencies. *) ApiDocs.GenerateHtml( @@ -429,7 +429,7 @@ ApiDocs.GenerateHtml( (** ## Rebasing Links -The `root` parameter is used for the base of page and image links in the generated documentation. By default it is derived from the project's `` property. +The `root` parameter is used for the base of page and image links in the generated documentation. By default, it is derived from the project's `` 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 `. diff --git a/docs/codeformat.fsx b/docs/codeformat.fsx index 3c36b4dfb..fe55d5274 100644 --- a/docs/codeformat.fsx +++ b/docs/codeformat.fsx @@ -33,7 +33,7 @@ This page demonstrates how to use `FSharp.Formatting.CodeFormat` to tokenize F# source code, obtain information about the source code (mainly tooltips from the type-checker) and how to turn the code into a nicely formatted HTML. -First, we need to load the assembly and open necessary namespaces: +First, we need to load the assembly and open the necessary namespaces: *) open FSharp.Formatting.CodeFormat @@ -81,7 +81,7 @@ as those used on [fssnip.net](http://www.fssnip.net) as documented in the Working with returned tokens ---------------------------- -Each returned snippet is essentially just a collection of lines and each line +Each returned snippet is essentially just a collection of lines, and each line consists of a sequence of tokens. The following snippet prints basic information about the tokens of our sample snippet: *) @@ -106,8 +106,8 @@ for (Line (_, tokens)) in lines do (** The `TokenSpan.Token` is the most important kind of token. It consists of a kind -(identifier, keyword, etc.), the original F# code and tool tip information. -The tool tip is further formatted using a simple document format, but we simply +(identifier, keyword, etc.), the original F# code and tooltip information. +The tooltip is further formatted using a simple document format, but we simply print the value using the F# pretty printing, so the result looks as follows: let hello[Literal "val hello : unit -> unit"; ...] () = @@ -165,6 +165,6 @@ If the input contains multiple snippets separated using the `//[snippet:...]` co *) (** -then the formatter returns multiple HTML blocks. However, the generated tool tips +then the formatter returns multiple HTML blocks. However, the generated tooltips are shared by all snippets (to save space) and so they are returned separately. *) diff --git a/docs/commandline.md b/docs/commandline.md index 78e836426..3f460cb9b 100644 --- a/docs/commandline.md +++ b/docs/commandline.md @@ -30,7 +30,7 @@ The command line options accepted are: | `--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 number. | +| `--nolinenumbers` | Don't add line numbers, the default is to add line numbers. | | `--parameters` | 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 | diff --git a/docs/content.fsx b/docs/content.fsx index 8b6b4ce58..186ad08a8 100644 --- a/docs/content.fsx +++ b/docs/content.fsx @@ -60,7 +60,7 @@ Content that is not `*.fsx` or `*.md` is copied across. ## Default Styling Content -By default additional content such as `fsdocs-search.js`, `fsdocs-tips.js` and `fsdocs-default.css` are included in the +By default additional content such as `fsdocs-search.js`, `fsdocs-tips.js` and `fsdocs-default.css` are included in the `content` directory of the output. This can be suppressed with `--nodefaultcontent` or by having your own copy of this content in your `content` directory. @@ -70,7 +70,7 @@ Any file or directory beginning with `.` is ignored. ## Front matter -Each content file can have optional frontmatter. This determines the navigation bar title, categorization ordering and meta tags. +Each content file can have an optional frontmatter. This determines the navigation bar title, categorization ordering and meta tags. For markdown, the format is: ``` @@ -105,7 +105,7 @@ The `keywords` are also used in a meta tag as part of `{{fsdocs-meta-tags}}`. Se ## Link Translation for Inputs -If an input is used in markdown as a target of a markdown direct link then that is replaced by the output file. For example: +If an input is used in markdown as a target of a markdown direct link, then that is replaced by the output file. For example: [Some Text](some-file.md) @@ -212,12 +212,12 @@ buttons to copy out the XmlDoc signature. HTML is generated by default. You can also add a `_template.html`. This should contain `{{fsdocs-content}}`, `{{fsdocs-tooltips}}` and other placeholders. Substitutions are applied to this template. -If a file `_template.html` exists then is used as the template for HTML generation for that directory and all sub-content. +If a file `_template.html` exists, then it's used as the template for HTML generation for that directory and all sub-content. ## Generating LaTeX output To generate .tex output for each script and markdown file, add a `_template.tex`. Substitutions are -applied to this template. The file is either empty of contains `{{fsdocs-content}}` as the key where the body +applied to this template. The file is either empty or contains `{{fsdocs-content}}` as the key where the body of the document is placed. ## Generating iPython Notebook output @@ -233,7 +233,7 @@ in your `docs` directory and use text like this: ## Generating Script outputs To generate .fsx output for each script and markdown file, add a `_template.fsx`, usually empty. Substitutions are -applied to this template. It is either empty of contains `{{fsdocs-content}}` as the key where the body +applied to this template. It is either empty or contains `{{fsdocs-content}}` as the key where the body of the script is placed. *) diff --git a/docs/evaluation.fsx b/docs/evaluation.fsx index a1237bb3c..ce06e490c 100644 --- a/docs/evaluation.fsx +++ b/docs/evaluation.fsx @@ -58,7 +58,7 @@ To include the meta output of F# Interactive processing such as type signatures (*** include-fsi-output ***) -To include both console otuput and F# Interactive output blended use `(*** include-fsi-merged-output ***)`. +To include both console output and F# Interactive output blended use `(*** include-fsi-merged-output ***)`. let test = 40 + 4 (*** include-fsi-merged-output ***) @@ -125,7 +125,7 @@ Literate.ToHtml(doc) (** When the `fsiEvaluator` parameter is specified, the script is evaluated and so you can use additional commands such as `include-value`. When the evaluator is *not* specified, -it is not created automatically and so the functionality is not available (this way, +it is not created automatically, so the functionality is not available (this way, you won't accidentally run unexpected code!) If you specify the `fsiEvaluator` parameter, but don't want a specific snippet to be evaluated @@ -136,14 +136,14 @@ The constructor of `cref:T:FSharp.Formatting.Literate.Evaluation.FsiEvaluator` t be used to specify, for example, defined symbols and other attributes for F# Interactive. You can also subscribe to the `EvaluationFailed` event which is fired whenever the evaluation -of an expression fails. You can use that to do tests that verify that all off the code in your +of an expression fails. You can use that to do tests that verify that all of the code in your documentation executes without errors. F# Formatting as a Library: Custom formatting functions --------------------------- As mentioned earlier, values are formatted using a simple `"%A"` formatter by default. -However, you can specify a formatting function that provides a nicer formatting for values +However, you can specify a formatting function that provides nicer formatting for values of certain types. For example, let's say that we would want to format F# lists such as `[1; 2; 3]` as HTML ordered lists `
    `. @@ -158,7 +158,7 @@ fsiEvaluator.RegisterTransformation(fun (o, ty, _executionCount) -> if ty.IsGenericType && ty.GetGenericTypeDefinition() = typedefof> then let items = - // Get items as objects and create paragraph for each item + // Get items as objects and create a paragraph for each item [ for it in Seq.cast (unbox o) -> [ Paragraph([ Literal(it.ToString(), None) ], None) ] ] // Return option value (success) with ordered list Some [ ListBlock(MarkdownListKind.Ordered, items, None) ] @@ -166,10 +166,10 @@ fsiEvaluator.RegisterTransformation(fun (o, ty, _executionCount) -> None) (** -The function is called with two arguments - `o` is the value to be formatted and `ty` +The function is called with two arguments - `o` is the value to be formatted, and `ty` is the static type of the value (as inferred by the F# compiler). The sample checks -that the type of the value is a list (containing values of any type) and then it -casts all values in the list to `obj` (for simplicity). Then we generate Markdown +that the type of the value is a list (containing values of any type), and then it +casts all values in the list to `obj` (for simplicity). Then, we generate Markdown blocks representing an ordered list. This means that the code will work for both LaTeX and HTML formatting - but if you only need one, you can simply produce HTML and embed it in `InlineHtmlBlock`. diff --git a/docs/literate.fsx b/docs/literate.fsx index ff42a0409..f456d0d00 100644 --- a/docs/literate.fsx +++ b/docs/literate.fsx @@ -51,7 +51,7 @@ F# script file with `.fsx` extension. Most of the features should be quite self- List.sum numbers (*** include-it ***) -The F# script files is processed as follows: +The F# script files are processed as follows: - A multi-line comment starting with `(**` and ending with `*)` is turned into text and is processed using the F# Markdown processor @@ -140,7 +140,7 @@ commands. Some of them are demonstrated in the following example: Console.WriteLine("Hello world!"); When processing the document, all F# snippets are copied to a separate file that -is type-checked using the F# compiler (to obtain colours and tool tips). +is type-checked using the F# compiler (to obtain colours and tooltips). The commands are written on the first line of the named snippet, wrapped in `[...]`: - The `hide` command specifies that the F# snippet should not be included in the @@ -190,7 +190,7 @@ The LaTeX will also be used in HTML and iPython notebook outputs. ### Making literate scripts work for different outputs -Literate scripts and markdown can by turned into LaTex, Python Notebooks and F# scripts. +Literate scripts and markdown can be turned into LaTex, Python Notebooks and F# scripts. A header may be needed to get the code to load, a typical example is this: @@ -212,9 +212,9 @@ A header may be needed to get the code to load, a typical example is this: #endif // IPYNB ``` -### Processing literate files programatically +### Processing literate files programmatically -To process file Use the two static methods to turn single documents into HTML +To process files use the two static methods to turn single documents into HTML as follows using functionality from the `cref:T:FSharp.Formatting.Literate.Literate` type: *) open System.IO @@ -233,7 +233,7 @@ Literate.ConvertMarkdownFile(doc, template) (** -The following sample also uses optional parameter `parameters` to specify additional +The following sample also uses the optional parameter `parameters` to specify additional keywords that will be replaced in the template file (this matches the `template-project.html` file which is included as a sample in the package): *) diff --git a/docs/markdown.fsx b/docs/markdown.fsx index 58dc54c36..13953676b 100644 --- a/docs/markdown.fsx +++ b/docs/markdown.fsx @@ -28,10 +28,10 @@ Markdown parser ============================== This page demonstrates how to use `FSharp.Formatting.Markdown` to parse a Markdown -document, process the obtained document representation and +document, process the obtained document representation, and how to turn the code into a nicely formatted HTML. -First, we need to load the assembly and open necessary namespaces: +First, we need to load the assembly and open the necessary namespaces: *) open FSharp.Formatting.Markdown @@ -158,7 +158,7 @@ Some span nodes (like emphasis) can contain other formatting, so we need to recu process children. This is done by matching against `MarkdownPatterns.SpanNodes` which is an active pattern that recognizes any node with children. The library also provides a _function_ named `MarkdownPatterns.SpanNode` that can be used to reconstruct the same node (when you want -to transform document). This is similar to how the `ExprShape` module for working with +to transform a document). This is similar to how the `ExprShape` module for working with F# quotations works. The function `collectParLinks` processes paragraphs - a paragraph cannot directly be a diff --git a/docs/sidebyside/sideextensions.md b/docs/sidebyside/sideextensions.md index 00fc31161..fb1c4144f 100644 --- a/docs/sidebyside/sideextensions.md +++ b/docs/sidebyside/sideextensions.md @@ -9,7 +9,7 @@ Example: Using the Markdown Extensions for LaTeX -To use LaTex extension, you need add javascript +To use LaTex extension, you need to add javascript link to [MathJax](http://www.mathjax.org/) in your template or inside a `_head.html` file. @@ -21,7 +21,7 @@ To use inline LaTex, eclose LaTex code with `$`: $ k_{n+1} = n^2 + k_n^2 - k_{n-1} $. Alternatively, you can also use `$$`. -To use block LaTex, start a new parapgraph, with +To use block LaTex, start a new paragraph, with the first line marked as `$$$` (no close `$$$`): $$$ diff --git a/docs/sidebyside/sidemarkdown.md b/docs/sidebyside/sidemarkdown.md index 4a81cfb9f..4ee74c914 100644 --- a/docs/sidebyside/sidemarkdown.md +++ b/docs/sidebyside/sidemarkdown.md @@ -14,7 +14,7 @@ package](http://fsprojects.github.io/FSharp.Formatting). In this case, the document itself is a valid Markdown and you can use standard Markdown features to format the text: - - Here is an example of unordered list and... + - Here is an example of an unordered list and... - Text formatting including **bold** and _emphasis_ For more information, see the [Markdown][md] reference. @@ -27,7 +27,7 @@ For more information, see the [Markdown][md] reference. In standard Markdown, you can include code snippets by writing a block indented by four spaces and the code snippet will be turned into a `
    ` element. If you do 
-the same using Literate F# tool, the code is turned into
+the same using the Literate F# tool, the code is turned into
 a nicely formatted F# snippet:
 
     /// The Hello World of functional languages!
@@ -50,9 +50,9 @@ the snippet should be placed in a separate module
     /// This is a hidden answer
     let answer = 42
 
-The value will be deffined in the F# code that is 
+The value will be defined in the F# code that is 
 processed and so you can use it from other (visible) 
-code and get correct tool tips:
+code and get correct tooltips:
 
     let answer = Hidden.answer
 
diff --git a/docs/sidebyside/sidescript.fsx b/docs/sidebyside/sidescript.fsx
index 846ceaabf..2f071e1de 100644
--- a/docs/sidebyside/sidescript.fsx
+++ b/docs/sidebyside/sidescript.fsx
@@ -12,7 +12,7 @@ files (`*.fsx`) that can be transformed into nice HTML
 using the `literate.fsx` script from the [F# Formatting
 package](http://fsprojects.github.io/FSharp.Formatting).
 
-As you can see, a comment starting with double asterisk
+As you can see, a comment starting with a double asterisk
 is treated as part of the document and is transformed
 using Markdown, which means that you can use:
 
@@ -25,7 +25,7 @@ And numerous other [Markdown][md] features.
 
 ## Writing F# code
 
-Code that is not inside comment will be formatted as
+Code that is not inside the comment will be formatted as
 a sample snippet.
 *)
 
@@ -50,8 +50,8 @@ let hidden = 42
 
 (**
 The value will be defined in the F# code and so you
-can use it from other (visible) code and get correct
-tool tips:
+can use it from other (visible) code and get the correct
+tooltips:
 *)
 
 let answer = hidden
@@ -64,14 +64,14 @@ has to be located at the end of the snippet (perhaps
 because it uses some definitions discussed in the middle).
 This can be done using `include` and `define` commands.
 
-The following snippet gets correct tool tips, even though
+The following snippet gets the correct tooltips, even though
 it uses `laterFunction`:
 *)
 
 (*** include:later-bit ***)
 
 (**
-Then we can explain how `laterFunction` is defined:
+Then, we can explain how `laterFunction` is defined:
 *)
 
 let laterFunction () = "Not very difficult, is it?"
diff --git a/docs/styling.md b/docs/styling.md
index 845214dc4..b24f1961c 100644
--- a/docs/styling.md
+++ b/docs/styling.md
@@ -38,7 +38,7 @@ this site.
 
 * Uses no styling parameters except those extracted from the project files.
 
-For your project, you don't need any of these files. However you can add them if you wish, though if
+For your project, you don't need any of these files. However, you can add them if you wish, though if
 you adjust them there is no guarantee that your template will continue to work with future versions of F# Formatting.
 
 ## Customizing via Styling Parameters
@@ -157,7 +157,7 @@ with the existing default template.
 ## Customizing menu items by template
 
 You can add advanced styling to the sidebar generated menu items by creating a new template for it.
-`fsdoc` will look for menu templates in the `--input` folder which defaults to the docs folder.
+`fsdoc` will look for menu templates in the `--input` folder, which defaults to the docs folder.
 
 To customize the generated menu-item headers, use file `_menu_template.html` with starting template:
 
@@ -168,13 +168,13 @@ To customize the generated menu-item headers, use file `_menu_template.html` wit
 {{fsdocs-menu-items}}
 ```
 
-Similarly, to customize the individual menu item list, use file `_menu-item_template.html` with starting template:
+Similarly, to customize the individual menu item list, use file `_menu-item_template.html` with the starting template:
 
 ```html
 
  1. {{fsdocs-menu-item-content}}
    2. 
 ```
 
-Do note that files need to be added prior running or won't be generated.
+Do note that files must be added before running, or won't be generated.
 In case you want to get a unique identifier for a header or menu item, you can use `{{fsdocs-menu-header-id}}`
 and `{{fsdocs-menu-item-id}}`, respectively.
 
@@ -193,7 +193,7 @@ The `FSharp.Formatting.ApiDocs` namespace includes a `GenerateModel` that captur
 the results of documentation preparation in `ApiDocsModel` and allows you to
 generate your own site using your own code.
 
-> NOTE: The ApiDocsModel API is undergoing change and improvement and there is no guarantee that your bespoke site
+> NOTE: The ApiDocsModel API is undergoing change and improvement, and there is no guarantee that your bespoke site
 > generation will continue to work
 > with future versions of F# Formatting.
 
diff --git a/docs/zero-to-hero.md b/docs/zero-to-hero.md
index cae141ec0..d272ff7e7 100644
--- a/docs/zero-to-hero.md
+++ b/docs/zero-to-hero.md
@@ -23,7 +23,7 @@ After we've installed the tool, we can run `dotnet fsdocs --help` and see the av
 Both `build` and `watch` will generate the documentation for a solution and an input folder.  
 The default folder for `--input` is the `./docs` folder, relative to the current working directory.
 
-Typically your project will be structured like:
+Typically, your project will be structured like this:
 
 ```
 /repository-root
@@ -36,7 +36,7 @@ Typically your project will be structured like:
     ./Project2/Project2.fsproj
 ```
 
-It is recommended to have a single solution at the root. In some editors, it is more convenient to open a solution at the root, to easily manipulate any file in root repository folder.  
+It is recommended to have a single solution at the root. In some editors, it is more convenient to open a solution at the root, to easily manipulate any file in the root repository folder.  
 When users clone your repository locally, they cannot be confused on how they need to open the project in their IDE.
 
 ⚠️ Please avoid putting your solution in the `src` folder. When we open that solution, it can be more difficult to edit files in the `docs` folder, as we can sometimes only see the `src` folder.
@@ -134,7 +134,7 @@ Deploy to Pages from GitHub Actions must be enabled in the repository settings:
 ![Enable deploy from Actions](./content/img/github-pages-settings.png)
 
 The typical flow is to publish your documentation after a release or after new commits were added to the default branch.  
-Let's create a very basic Action that will deploy our website after pushing to main:
+Let's create a very basic Action that will deploy our website after pushing to the main:
 
 Create a file `.github/workflows/docs.yml`:
 
@@ -260,4 +260,4 @@ jobs:
       run: dotnet fsdocs build
 ```
 
-⚠️ Also never trust any update to `fsdocs` blindly, always check the [release notes](https://github.com/fsprojects/FSharp.Formatting/blob/main/RELEASE_NOTES.md) to see if there are any breaking changes.
+⚠️ Also, never trust any update to `fsdocs` blindly, always check the [release notes](https://github.com/fsprojects/FSharp.Formatting/blob/main/RELEASE_NOTES.md) to see if there are any breaking changes.