Skip to content

Commit

Permalink
fix script links in nested directories
Browse files Browse the repository at this point in the history
  • Loading branch information
Don Syme committed Jul 29, 2021
1 parent 3c5b359 commit 14e78e6
Show file tree
Hide file tree
Showing 6 changed files with 106 additions and 106 deletions.
48 changes: 24 additions & 24 deletions docs/apidocs.fsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,21 +27,21 @@ 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)
[![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
38 changes: 19 additions & 19 deletions docs/codeformat.fsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,13 @@ index: 1

(**
[![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)
[![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
44 changes: 22 additions & 22 deletions docs/content.fsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ 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)
[![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

0 comments on commit 14e78e6

Please sign in to comment.