Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix 696, 695 #697

Merged
merged 5 commits into from
Jul 29, 2021
+188 −204
Merged

Fix 696, 695 #697

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
14e78e6
fix script links in nested directories
Jul 29, 2021
0d81d37
fix https://github.com/fsprojects/FSharp.Formatting/issues/695
Jul 29, 2021
3bcc342
fix
Jul 29, 2021
db88065
fix
Jul 29, 2021
da5afa0
fix
Jul 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 0 additions & 24 deletions docs/README.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,6 @@

The `Dockerfile` and `NuGet.config` allow us to run generated notebooks in [MyBinder](https://mybinder.org)

* `gh-pages` branch of dsyme/DiffSharp: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/dsyme/DiffSharp/gh-pages)

* `index.ipynb` for `dev` branch of dsyme/DiffSharp: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/dsyme/DiffSharp/gh-pages?filepath=index.ipynb)

# Generating docs

This published version of the docs can be refreshed by these commands:

1. Prepare one off

dotnet tool restore
git clone https://github.com/dsyme/DiffSharp ../DiffSharp-docs -b gh-pages --depth 1

2. Build

dotnet build
dotnet fsdocs build --clean --output ../DiffSharp-docs
bash -c "(cd ../DiffSharp-docs && git add . && git commit -a -m doc-update && git push -f https://github.com/dsyme/DiffSharp gh-pages)"

To use a local builg of FSharp.Formatting:

git clone https://github.com/fsprojects/FSharp.Formatting ../FSharp.Formatting
cd ..\FSharp.Formatting
.\build

# How it works

Expand Down
1 change: 0 additions & 1 deletion docs/_template.fsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +0,0 @@

50 changes: 25 additions & 25 deletions docs/apidocs.fsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,22 +26,22 @@ index: 5
let root = "C:\\"

(**
[![Binder](img/badge-binder.svg)](https://mybinder.org/v2/gh/diffsharp/diffsharp.github.io/master?filepath={{fsdocs-source-basename}}.ipynb) 
[![Script](img/badge-script.svg)]({{fsdocs-source-basename}}.fsx) 
[![Notebook](img/badge-notebook.svg)]({{fsdocs-source-basename}}.ipynb)
[![Binder](img/badge-binder.svg)](https://mybinder.org/v2/gh/fsprojects/fsharp.formatting/master?filepath={{fsdocs-source-basename}}.ipynb) 
[![Script](img/badge-script.svg)]({{root}}/{{fsdocs-source-basename}}.fsx) 
[![Notebook](img/badge-notebook.svg)]({{root}}/{{fsdocs-source-basename}}.ipynb)

API Documentation Generation
====================================

The [command-line tool `fsdocs`](commandline.html) can be used to generate documentation
The [command-line tool `fsdocs`](commandline.html) can be used to generate documentation
for F# libraries with XML comments. The documentation is normally built using `fsdocs build` and developed using `fsdocs watch`. For
the former the output will be placed in `output\reference` by default.

## Templates

The HTML is built by instantiating a template. The template used is the first of:

* `docs/reference/_template.html`
* `docs/reference/_template.html`

* `docs/_template.html`

Expand All @@ -57,11 +57,11 @@ The tags that form the core of the XML doc specification are:

```
<c> <para> <see>* <value>
<code> <param>* <seealso>*
<example> <paramref> <summary>
<exception>* <permission>* <typeparam>*
<include>* <remarks> <typeparamref>
<list> <inheritdoc> <returns>
<code> <param>* <seealso>*
<example> <paramref> <summary>
<exception>* <permission>* <typeparam>*
<include>* <remarks> <typeparamref>
<list> <inheritdoc> <returns>
```

In addition, you may also use the [Recommended XML doc extensions for F# documentation tooling](https://github.com/fsharp/fslang-design/blob/master/tooling/FST-1031-xmldoc-extensions.md).
Expand All @@ -75,7 +75,7 @@ In addition, you may also use the [Recommended XML doc extensions for F# documen
* `<exclude>` to exclude from XML docs

* `<category>` to give a category for an entity or member. An optional `index` attribute can be specified
to help sort the list of categories.
to help sort the list of categories.

* `\(...\)` for inline math and `$$...$$` and `\[...\]`for math environments, see http://docs.mathjax.org.
Some escaping of characters (e.g. `&lt;`, `&gt;`) may be needed to form valid XML
Expand All @@ -92,7 +92,7 @@ An example of an XML documentation comment, assuming the code is in namespace `T
/// <remarks>More on that</remarks>
/// </namespacedoc>
///
module SomeModule =
module SomeModule =
/// <summary>
/// Some actual comment
/// <para>Another paragraph, see <see cref="T:TheNamespace.SomeType"/>. </para>
Expand All @@ -115,7 +115,7 @@ module SomeModule =

/// <summary>
/// A type, see <see cref="T:TheNamespace.SomeModule"/> and
/// <see cref="M:TheNamespace.SomeModule.someFunction"/>.
/// <see cref="M:TheNamespace.SomeModule.someFunction"/>.
/// </summary>
///
type SomeType() =
Expand All @@ -127,7 +127,7 @@ Like types, members are referred to by xml doc sig. These must currently be pre
compiler doesn't elaborate these references from simpler names:
*)

type Class2() =
type Class2() =
member this.Property = "more"
member this.Method0() = "more"
member this.Method1(c: string) = "more"
Expand All @@ -143,7 +143,7 @@ let referringFunction1 () = "result"
Generic types are referred to by .NET compiled name, e.g.
*)

type GenericClass2<'T>() =
type GenericClass2<'T>() =
member this.Property = "more"

member this.NonGenericMethod(_c: 'T) = "more"
Expand Down Expand Up @@ -171,7 +171,7 @@ This is normally done automatically based on the following settings:
If your source is not built from the same project where you are building documentation then
you may need these settings:

<FsDocsSourceRepository>...</FsDocsSourceRepository> -- the URL for the root of the source
<FsDocsSourceRepository>...</FsDocsSourceRepository> -- the URL for the root of the source
<FsDocsSourceFolder>...</FsDocsSourceFolder> -- the root soure folder at time of build

It is assumed that `sourceRepo` and `sourceFolder` have synchronized contents.
Expand Down Expand Up @@ -204,25 +204,25 @@ If a type with the given name is not found in the same assembly the link will no
*)

/// Contains two types [Bar] and [Foo.Baz]
module Foo =
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) =
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
/// 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
Expand All @@ -236,7 +236,7 @@ It needs to be set on a separate tripple-slashed line, but it could be either th
*)
/// [omit]
/// Some actual comment
module Bar =
module Bar =
let a = 42
(**

Expand All @@ -256,9 +256,9 @@ For example the `cref:M:FSharp.Formatting.ApiDocs.ApiDocs.GenerateHtml` method:
*)

let file = Path.Combine(root, "bin/YourLibrary.dll")
let input = ApiDocInput.FromFile(file)
let input = ApiDocInput.FromFile(file)
ApiDocs.GenerateHtml
( [ input ],
( [ input ],
output=Path.Combine(root, "output"),
collectionName="YourLibrary",
template=Path.Combine(root, "templates", "template.html"),
Expand Down
40 changes: 20 additions & 20 deletions docs/codeformat.fsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,14 @@ index: 1
#endif // IPYNB

(**
[![Binder](img/badge-binder.svg)](https://mybinder.org/v2/gh/diffsharp/diffsharp.github.io/master?filepath={{fsdocs-source-basename}}.ipynb)&emsp;
[![Script](img/badge-script.svg)]({{fsdocs-source-basename}}.fsx)&emsp;
[![Notebook](img/badge-notebook.svg)]({{fsdocs-source-basename}}.ipynb)
[![Binder](img/badge-binder.svg)](https://mybinder.org/v2/gh/fsprojects/fsharp.formatting/master?filepath={{fsdocs-source-basename}}.ipynb)&emsp;
[![Script](img/badge-script.svg)]({{root}}/{{fsdocs-source-basename}}.fsx)&emsp;
[![Notebook](img/badge-notebook.svg)]({{root}}/{{fsdocs-source-basename}}.ipynb)

Code formatting
==============================

This page demonstrates how to use `FSharp.Formatting.CodeFormat` to tokenize
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.

Expand All @@ -52,9 +52,9 @@ can be called to format snippets repeatedly:
let formattingAgent = CodeFormat.CreateAgent()

(**
If you want to process multiple snippets, it is a good idea to keep the
If you want to process multiple snippets, it is a good idea to keep the
formatting agent around if possible. The agent needs to load the F# compiler
(which needs to load various files itself) and so this takes a long time.
(which needs to load various files itself) and so this takes a long time.

Processing F# source
--------------------
Expand All @@ -65,7 +65,7 @@ To call the method, we define a simple F# code as a string:
*)

let source = """
let hello () =
let hello () =
printfn "Hello world"
"""
let snippets, errors = formattingAgent.ParseAndCheckSource("C:\\snippet.fsx", source)
Expand All @@ -76,10 +76,10 @@ of the script file. The file does not have to physically exist. It is used by th
F# compiler to resolve relative references (e.g. `#r`) and to automatically name
the module including all code in the file.

You can also specify additional parameters, such as `*.dll` references, by passing
a third argument with compiler options (e.g. `"-r:Foo.dll -r:Bar.dll"`).
You can also specify additional parameters, such as `*.dll` references, by passing
a third argument with compiler options (e.g. `"-r:Foo.dll -r:Bar.dll"`).

This operation might take some time, so it is a good idea to use an asynchronous
This operation might take some time, so it is a good idea to use an asynchronous
variant of the method. It returns two arrays - the first contains F# snippets
in the source code and the second contains any errors reported by the compiler.
A single source file can include multiple snippets using the same formatting tags
Expand All @@ -90,7 +90,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:
*)
Expand All @@ -102,38 +102,38 @@ let (Snippet(title, lines)) = snippets |> Seq.head
for (Line(_, tokens)) in lines do
for token in tokens do
match token with
| TokenSpan.Token(kind, code, tip) ->
| TokenSpan.Token(kind, code, tip) ->
printf "%s" code
tip |> Option.iter (fun spans ->
printfn "%A" spans)
| TokenSpan.Omitted _
| TokenSpan.Output _
printfn "%A" spans)
| TokenSpan.Omitted _
| TokenSpan.Output _
| TokenSpan.Error _ -> ()
printfn ""

(**
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
The tool tip 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"; ...] () =
let hello[Literal "val hello : unit -> unit"; ...] () =
printfn[Literal "val printfn : TextWriterFormat<'T> -> 'T"; ...] "Hello world"

The `Omitted` token is generated if you use the special `(*[omit:...]*)` command.
The `Output` token is generated if you use the `// [fsi:...]` command to format
output returned by F# interactive. The `Error` command wraps code that should be
output returned by F# interactive. The `Error` command wraps code that should be
underlined with a red squiggle if the code contains an error.

Generating HTML output
----------------------

Finally, the `CodeFormat` type also includes a method `cref:M:FSharp.Formatting.CodeFormat.CodeFormat.FormatHtml` that can be used
to generate nice HTML output from an F# snippet. This is used, for example, on
to generate nice HTML output from an F# snippet. This is used, for example, on
[F# Snippets](http://www.fssnip.net). The following example shows how to call it:
*)

let prefix = "fst"
let prefix = "fst"
let html = CodeFormat.FormatHtml(snippets, prefix)

// Print all snippets, in case there is more of them
Expand Down
46 changes: 23 additions & 23 deletions docs/content.fsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ index: 3


(**
[![Binder](img/badge-binder.svg)](https://mybinder.org/v2/gh/diffsharp/diffsharp.github.io/master?filepath={{fsdocs-source-basename}}.ipynb)&emsp;
[![Script](img/badge-script.svg)]({{fsdocs-source-basename}}.fsx)&emsp;
[![Notebook](img/badge-notebook.svg)]({{fsdocs-source-basename}}.ipynb)
[![Binder](img/badge-binder.svg)](https://mybinder.org/v2/gh/fsprojects/fsharp.formatting/master?filepath={{fsdocs-source-basename}}.ipynb)&emsp;
[![Script](img/badge-script.svg)]({{root}}/{{fsdocs-source-basename}}.fsx)&emsp;
[![Notebook](img/badge-notebook.svg)]({{root}}/{{fsdocs-source-basename}}.ipynb)

Creating Content
===================================
Expand Down Expand Up @@ -123,30 +123,30 @@ generated outputs.

See [Styling](styling.html) for information about template parameters and styling beyond the default template.

| Substitution name | Generated content |
| Substitution name | Generated content |
|:------------------------------|:--------------------------------------------------------------|
| `root` | `<PackageProjectUrl>` else `/` followed by `fsdocs-collection-name` |
| `fsdocs-collection-name` | Name of .sln, single .fsproj or containing directory |
| `fsdocs-content` | Main page content |
| `fsdocs-list-of-namespaces` | HTML `<li>` list of namespaces with links |
| `fsdocs-list-of-documents` | HTML `<li>` list of documents with titles and links |
| `fsdocs-page-title` | First h1 heading in literate file. Generated for API docs |
| `fsdocs-source` | Original literate script or markdown source |
| `fsdocs-source-filename` | Name of original input source, relative to the `docs` root |
| `fsdocs-source-basename` | Name of original input source, excluding its extensions, relative to the `docs` root |
| `fsdocs-tooltips` | Generated hidden div elements for tooltips |
| `root` | `<PackageProjectUrl>` else `/` followed by `fsdocs-collection-name` |
| `fsdocs-collection-name` | Name of .sln, single .fsproj or containing directory |
| `fsdocs-content` | Main page content |
| `fsdocs-list-of-namespaces` | HTML `<li>` list of namespaces with links |
| `fsdocs-list-of-documents` | HTML `<li>` list of documents with titles and links |
| `fsdocs-page-title` | First h1 heading in literate file. Generated for API docs |
| `fsdocs-source` | Original literate script or markdown source |
| `fsdocs-source-filename` | Name of original input source, relative to the `docs` root |
| `fsdocs-source-basename` | Name of original input source, excluding its extensions, relative to the `docs` root |
| `fsdocs-tooltips` | Generated hidden div elements for tooltips |
| `fsdocs-watch-script` | The websocket script used in watch mode to trigger hot reload |

The following substitutions are extracted from your project files and may or may not be used by the default
template:

| Substitution name | Value |
|:-------------------------------------|:-------------------------------|
| `fsdocs-copyright` | `<Copyright>` |
| `fsdocs-package-project-url` | `<PackageProjectUrl>` |
| Substitution name | Value |
|:-------------------------------------|:-------------------------------|
| `fsdocs-copyright` | `<Copyright>` |
| `fsdocs-package-project-url` | `<PackageProjectUrl>` |
| `fsdocs-package-license-expression` | `<PackageLicenseExpression>` |
| `fsdocs-package-tags` | `<PackageTags>` |
| `fsdocs-package-version` | `<Version>` |
| `fsdocs-package-tags` | `<PackageTags>` |
| `fsdocs-package-version` | `<Version>` |

For the `fsdocs` tool, additional substitutions can be specified using `--parameters`.

Expand Down Expand Up @@ -196,7 +196,7 @@ If a file `_template.html` exists then is used as the template for HTML generati

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
of the document is placed.
of the document is placed.

## Generating iPython Notebook output

Expand All @@ -207,11 +207,11 @@ To add a `mybinder` badge to your generated notebook, ensure you have a `Dockerf
in your `docs` directory and use text like this:

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/fsprojects/FSharp.Formatting/gh-pages?filepath=literate.ipynb)

## 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
of the script is placed.
of the script is placed.

*)
Loading