fsprojects / fsharp.formatting

F# tools for generating documentation (Markdown processor and F# code formatter)

fsdocs and FSharp.Formatting

The FSharp.Formatting package includes libraries and tools for processing F# script files, markdown and components for documentation generation. The primary tool is "fsdocs".

See https://fsprojects.github.io/FSharp.Formatting/

Development

dotnet fsi build.fsx

Once built, you can run the command-line tool to self-build the docs for this directory using

dotnet build
src\fsdocs-tool\bin\Debug\net6.0\fsdocs.exe watch
src\fsdocs-tool\bin\Debug\net6.0\fsdocs.exe build --clean

Pipelines

Run

dotnet fsi build.fsx -- --help

to see what other pipelines can be run from build.fsx.

dotnet fsi build.fsx -- -p Verify

Will perform the linting, unit tests and analyzer check. This is useful to run locally before submitting your PR.

Maintainer(s)

• @dsyme
• @baronfel
• @nhirschey
• @nojaf

fsharp.formatting's Issues

Line numbers in generated F# snippets in html

It would be nice if when selecting the content of the F# snippets embedded in the generated html the line numbers weren't copied also. Most embedded code on blogs do that either by using embedded gists from http://gist.github.com or some variation of this javascript lib http://alexgorbatchev.com/SyntaxHighlighter/
Both fssnip and all the html generated by literate.fsx have this problem. In fssnip it's not a problem because you have the copy source button

Incorrect indentation

Given:

paragraph

       b
    a

another paragraph

the additional spaces in the first line of <pre> are ignored

Support of markdown extensions

Tomas,

A)
I want to suggest to support tables and extend pure markdown syntax. The format of tables can be taken from github and/or pandoc.

I've added support of simple tables in my pandoc-tables branch of FSharp.Formatting

------ --------------- ----------
**Id** **Description** **Link**
1      _text_          [url](url)
2      *text*          [url](url)

I also would like to extend it to support multiline cells.

B)
In one of my current projects I'm using pandoc to generate both pdf and html documents from the same source. Documents contain math expressions so i use pandoc math extension. The syntax is similar to the one used on stackexchange. I want to switch from pandoc to FSharp.Markdown in this project but need support of math expressions.

What do you think about this features (tables and mathematics)? If you agree that they are useful then I will work on them (we also should discuss syntax in this case).

Add more tests

There are now separate test projects, but most of them are still just exe files that you can run to test things by hand. We should turn those into unit tests...

The only one that has the right structure is CodeFormat.Tests, so this can be used as an inspiration how the structure should look.

I'd welcome any contributions here :-) feel free to turn other projects in tests folder into proper Library projects that reference NUnit, include FsUnit.fs and contain some actual tests!

For Markdown, it would be nice to compare against some existing tools (there are some sample outputs in Benchmarks folder) but we do not necessarily have to do exactly the same thing...

Problem when rendering one-line code blocks

Hi,

I have a small sample code in my API docs:

but somehow this is not rendered in a pre-tag:

Linking to other types

Hi,

I would like to link to other types or functions from the API docs.

type MyTape = int

/// This returns a [MyType].
let f x :MyType = x * 2

Maybe this introduces magic, but it still looks a bit like ordinary markdown linking.

Space after "*)"

If there is a space after (** ... *) in literate script, then things break...

Off by one error during render process in API docs?

Hi,

I'm trying to add sample code to the FAKE API docs (see http://fsharp.github.io/FAKE/apidocs/fake-xpkghelper.html). But whatever I do, I'm always getting one character rendered to the next line.

Maybe there is a "off by one" error somewhere?!

Cheers,
Steffen

Render multiple assemblies in one step

Hi,

at the moment I do this:

MetadataFormat.Generate ( 
    "./build/FakeLib.dll", 
    apidocsDir, 
    ["./help/templates/reference/"])

But I'd like to do this:

MetadataFormat.Generate ( 
    ["./build/FakeLib.dll"; "./build/Fake.SQL.dll"], 
    apidocsDir, 
    ["./help/templates/reference/"])

Any chance you can do this?

Default font

The current default font is a little hard to read. The a's are a little weird, and some letters like the r don't align propertly to the baseline:

I still like it better than the old one (still used on http://fsharp.github.io/FSharp.Data/), but I think the one used by http://funscript.info/index.html would be a better choice for the default.

Concept misunderstanding

I am a newbie in FSharp.Formatting and try to understand how I can use it. I have some misunderstanding of overall concept and cannot find a way to build what I need.

As I understand, current goal of Literate is to transform *.fsx or *.md file to *.html according to template (one-to-one transformation). But, when I build a site, my primary goal is to get an *.html using some *.fsx and/or .md files (many-to-one transformation).

As a first step, I choose my page layout, after that I split my page into zones for different kinds of content and want to have an ability to bind zones to source *.fsx/*.md files. Something like this:

let template = source + "page-template.html"
let zoneBindings=
  [ "main", "intro.md"
    "left", "fs-sample.fsx"
    "right", "cs-sample.md"]

Literate.BuildHTML
  (template, source + "\\output\\index.html", bindings = zoneBindings)

How can I build page with following layout using current version of FSharp.Formatting.Literate?

Please correct me if I am wrong or miss something.
Thanks.

Documentation for the default constructor

Hi,

writing

leads to:

How can I document the default constructor?

Provide default API templates

So that project can normally just use the included templates....

Render properties of a record type

Hi,

I have a record type defined like this:

and it is rendered as:

It would be nice if the properties FSharp.Formatting would also render the properties.

Cheers,
Steffen

Fix module ordering in API docs

Hi,

it's nice to have modules in order but please change

to alphabetical order (instead of reverse alphabetical order).

Cheers,
Steffen

Make it super easy to copy code samples to the clipboard

Hi,

I'm trying the Deedle tutorial and noticed the following:

I think it's a good idea to have these inline output messages, but it's "really hard" 🐹 to copy this stuff into a fsx file.

There should be an easier way to copy samples.

Cheers,
Steffen

Headings ending with # are not parsed correctly

For example

## Hello F#

Becomes "Hello F"

Render simple http.// links

Hi,

in github's version of markdown you can simply write an URL (without any brackets) and it's rendered as a link. This would be nice for compatibility.

Cheers,
Steffen

"go to definition" for API docs

Hi, I really like the new API documenting features. I'm already using them for Fake.

One thing I'd like to see is a "go to definition" link for all generated function / module docs.

This feature would allow me to browse from the docs directly to the github sources if I need further information.

What do you think?

use Fake ?

Would this project no benefit from using Fake ?

what do you think ?

Highlight F# code in API docs samples

Hi,

I used F# sample code in the API docs (see http://fsharp.github.io/FAKE/apidocs/fake-xpkghelper.html). Would be cool if you could hightlight this like the rest of FSharp.Formatting does.

Cheers,
Steffen

Future directions

The tool is already useful as it is at current state. But I think there are still rooms for improvements. It would be beneficial if you (and others who are interested in) could share what you would like to improve further.

I think the tool is a great addition to F# ecosystem, and would like to contribute from time to time. Having a TODO list is great for that purpose.

From my experience working on the code base, there are two important things to do:

• Support Math extensions
• Create unit tests

Please share your thoughts.

fsharp.core references are missing in projects

which means Fsharp.core will default to 4.3.1 when compiled in VS 2013, which leads tests to fail on a type initialisation "method not found InteractiveChecker.Create"

Explicit references to the specific version of FSharp.Core would pin that moving part down.

Render the namespace in detail pages

Hi,

I just noticed there is no namespace information on the details pages. This might be a problem if someone googles the page:

Cheers,
Steffen

Missing compiler directive from Markdown

Hi,

I'm trying to port my FAKE docs to FSharp.Formatting. Unfortunately there is an issue with compiler directives in markdown files.

FSharp.Formatting converts #r to # (it removes the "r").

See http://fsharp.github.io/FAKE/gettingstarted.html

Support [fsi: ... ] tags in Markdown documents

It does not seem to be working...

Transform Markdown to XML doc

When using Markdown for writing comments, the comments look something like:

/// Adds two numbers
///
/// ## Parameters
///  - `a` - First number
///  - `b` - Second number
///
/// ## Example
///
///     let n = add 40 2
///
let add a b = a + b

Provided that this format is used consistently, we should be able to turn the XML file generated by the compiler into XML file that contains the usual XML documentation expected by Visual Studio (to make tooltips work etc.). In this case:

<summary>Adds two numbers</summary>
<param name="a">First number</param>
<param name="b">First number</param>
<code><c>
   let n = add 40 2
</c></code>

...or something along those lines. This is really just a matter of simple XML transformation using the Markdown parser.

Strange formatting error and reference to strange path

Hi,

@Heather reported a build error at fsprojects/FAKE#176.
I closed the issue for FAKE and reopened it here.

I think there is a problem with the intergration of the PowerPack.

The path C:\dev is very strange.

Cheers,
Steffen

Don't render static private members

Hi,

renders:

It's private and therefor I think it should be omitted.

Cheers,
Steffen

Support for double-backticks

Hi Tomas,

I've spotted a small issue: when I use double-backticked functions, the tooltip is not displayed. Here is a small repro .fsx file:

let foo = ()

let f oo = ()

When the generated HTML is viewed, the first function will correctly display the tooltip, but the second won't.

If I get time I'll see if I can understand enough of the implementation to fix it.

Thanks
Akash

Problems when rendering globbing paths

Hi,

for FAKE docs I want to render:

but it creates:

Cheers,
Steffen

mono issue

Document compilation crash on mono

~/c/FSharp.Formatting git:master ❯❯❯ fsharpi tools/build.fsx                                                                                                                                                                      
Generating 'codeformat.html'
System.Exception: Exception: System.Exception (No method '.ctor' with 7 arguments found)

Stack trace:   at Microsoft.FSharp.Core.ExtraTopLevelOperators+PrintFormatToStringThenFail@137-1[System.Object].Invoke (System.String message) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.PrintfModule+PrintFormatToStringThen@590-3[System.Object].Invoke (Microsoft.FSharp.Core.Unit unitVar0) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.PrintfImpl.go@530-3[Unit,String,Object] (System.String fmt, Int32 len, Microsoft.FSharp.Core.FSharpFunc`2 outputChar, Microsoft.FSharp.Core.FSharpFunc`2 outa, Microsoft.FSharp.Core.Unit os, Microsoft.FSharp.Core.FSharpFunc`2 finalize, Microsoft.FSharp.Collections.FSharpList`1 args, Int32 i) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.PrintfImpl.run@528[Unit,String,Object] (Microsoft.FSharp.Core.FSharpFunc`2 initialize, System.String fmt, Int32 len, Microsoft.FSharp.Collections.FSharpList`1 args) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.PrintfImpl.capture@547[Unit,String,Object] (Microsoft.FSharp.Core.FSharpFunc`2 initialize, System.String fmt, Int32 len, Microsoft.FSharp.Collections.FSharpList`1 args, System.Type ty, Int32 i) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.PrintfImpl+capture@547-1[Microsoft.FSharp.Core.Unit,System.String,System.Object].Invoke (Microsoft.FSharp.Collections.FSharpList`1 args, System.Type ty, Int32 i) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.FSharpFunc`2[Microsoft.FSharp.Collections.FSharpList`1[System.Object],System.Type].InvokeFast[Int32,Object] (Microsoft.FSharp.Core.FSharpFunc`2 func, Microsoft.FSharp.Collections.FSharpList`1 arg1, System.Type arg2, Int32 arg3) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.FSharpFunc`2[System.Type,System.Object].InvokeFast[Object] (Microsoft.FSharp.Core.FSharpFunc`2 func, System.Type arg1, System.Object arg2) [0x00000] in <filename unknown>:0 
  at [e-mail] (System.Object inp) [0x00000] in <filename unknown>:0 
  at <StartupCode$FSharp-Core>.$Reflect+Invoke@727-4[System.Int32,System.Object].Invoke (Int32 inp) [0x00000] in <filename unknown>:0 
  at [email protected] (Int32 arg20) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.FSharpFunc`2[System.String,System.Int32].InvokeFast[Object] (Microsoft.FSharp.Core.FSharpFunc`2 func, System.String arg1, Int32 arg2) [0x00000] in <filename unknown>:0 
  at [email protected] (System.Object args) [0x00000] in <filename unknown>:0 
  at <StartupCode$FSharp-Core>.$Reflect+Invoke@727-4[System.Tuple`7[System.Int32,System.Int32,System.Int32,System.Int32,System.Object,System.Int32,System.String],System.Object].Invoke (System.Tuple`7 inp) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Compiler.SourceCodeServices+TokenInformation.WithRightColumn (Int32 rightColumn) [0x00000] in <filename unknown>:0 
  at FSharp.CodeFormat.CommentFilter.mergeComments (Microsoft.FSharp.Collections.FSharpList`1 line, Microsoft.FSharp.Core.FSharpOption`1 cmt, Microsoft.FSharp.Collections.FSharpList`1 acc) [0x00000] in <filename unknown>:0 
  at [e-mail] (IEnumerable`1& next) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.CompilerServices.GeneratedSequenceBase`1[System.Tuple`2[System.Int32,Microsoft.FSharp.Collections.FSharpList`1[System.Tuple`2[System.String,Microsoft.FSharp.Compiler.SourceCodeServices+TokenInformation]]]].MoveNextImpl () [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.CompilerServices.GeneratedSequenceBase`1[System.Tuple`2[System.Int32,Microsoft.FSharp.Collections.FSharpList`1[System.Tuple`2[System.String,Microsoft.FSharp.Compiler.SourceCodeServices+TokenInformation]]]].System-Collections-IEnumerator-MoveNext () [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Collections.SeqModule.ToList[Tuple`2] (IEnumerable`1 source) [0x00000] in <filename unknown>:0 
  at FSharp.CodeFormat.CommentFilter.shrinkOmittedParts (Microsoft.FSharp.Collections.FSharpList`1 source) [0x00000] in <filename unknown>:0 
  at <StartupCode$FSharp-CodeFormat>[email protected] (System.Tuple`2 _arg3) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Control.AsyncBuilderImpl+args@762[System.Tuple`2[Microsoft.FSharp.Compiler.SourceCodeServices+TypeCheckInfo,Microsoft.FSharp.Compiler.SourceCodeServices+ErrorInfo[]],System.Tuple`2[Microsoft.FSharp.Collections.FSharpList`1[FSharp.CodeFormat.Snippet],FSharp.CodeFormat.SourceError[]]].Invoke (System.Tuple`2 a) [0x00000] in <filename unknown>:0 

 ---> System.Exception: No method '.ctor' with 7 arguments found
  at Microsoft.FSharp.Core.ExtraTopLevelOperators+PrintFormatToStringThenFail@137-1[System.Object].Invoke (System.String message) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.PrintfModule+PrintFormatToStringThen@590-3[System.Object].Invoke (Microsoft.FSharp.Core.Unit unitVar0) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.PrintfImpl.go@530-3[Unit,String,Object] (System.String fmt, Int32 len, Microsoft.FSharp.Core.FSharpFunc`2 outputChar, Microsoft.FSharp.Core.FSharpFunc`2 outa, Microsoft.FSharp.Core.Unit os, Microsoft.FSharp.Core.FSharpFunc`2 finalize, Microsoft.FSharp.Collections.FSharpList`1 args, Int32 i) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.PrintfImpl.run@528[Unit,String,Object] (Microsoft.FSharp.Core.FSharpFunc`2 initialize, System.String fmt, Int32 len, Microsoft.FSharp.Collections.FSharpList`1 args) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.PrintfImpl.capture@547[Unit,String,Object] (Microsoft.FSharp.Core.FSharpFunc`2 initialize, System.String fmt, Int32 len, Microsoft.FSharp.Collections.FSharpList`1 args, System.Type ty, Int32 i) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.PrintfImpl+capture@547-1[Microsoft.FSharp.Core.Unit,System.String,System.Object].Invoke (Microsoft.FSharp.Collections.FSharpList`1 args, System.Type ty, Int32 i) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.FSharpFunc`2[Microsoft.FSharp.Collections.FSharpList`1[System.Object],System.Type].InvokeFast[Int32,Object] (Microsoft.FSharp.Core.FSharpFunc`2 func, Microsoft.FSharp.Collections.FSharpList`1 arg1, System.Type arg2, Int32 arg3) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.FSharpFunc`2[System.Type,System.Object].InvokeFast[Object] (Microsoft.FSharp.Core.FSharpFunc`2 func, System.Type arg1, System.Object arg2) [0x00000] in <filename unknown>:0 
  at [e-mail] (System.Object inp) [0x00000] in <filename unknown>:0 
  at <StartupCode$FSharp-Core>.$Reflect+Invoke@727-4[System.Int32,System.Object].Invoke (Int32 inp) [0x00000] in <filename unknown>:0 
  at [email protected] (Int32 arg20) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.FSharpFunc`2[System.String,System.Int32].InvokeFast[Object] (Microsoft.FSharp.Core.FSharpFunc`2 func, System.String arg1, Int32 arg2) [0x00000] in <filename unknown>:0 
  at [email protected] (System.Object args) [0x00000] in <filename unknown>:0 
  at <StartupCode$FSharp-Core>.$Reflect+Invoke@727-4[System.Tuple`7[System.Int32,System.Int32,System.Int32,System.Int32,System.Object,System.Int32,System.String],System.Object].Invoke (System.Tuple`7 inp) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Compiler.SourceCodeServices+TokenInformation.WithRightColumn (Int32 rightColumn) [0x00000] in <filename unknown>:0 
  at FSharp.CodeFormat.CommentFilter.mergeComments (Microsoft.FSharp.Collections.FSharpList`1 line, Microsoft.FSharp.Core.FSharpOption`1 cmt, Microsoft.FSharp.Collections.FSharpList`1 acc) [0x00000] in <filename unknown>:0 
  at [e-mail] (IEnumerable`1& next) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.CompilerServices.GeneratedSequenceBase`1[System.Tuple`2[System.Int32,Microsoft.FSharp.Collections.FSharpList`1[System.Tuple`2[System.String,Microsoft.FSharp.Compiler.SourceCodeServices+TokenInformation]]]].MoveNextImpl () [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.CompilerServices.GeneratedSequenceBase`1[System.Tuple`2[System.Int32,Microsoft.FSharp.Collections.FSharpList`1[System.Tuple`2[System.String,Microsoft.FSharp.Compiler.SourceCodeServices+TokenInformation]]]].System-Collections-IEnumerator-MoveNext () [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Collections.SeqModule.ToList[Tuple`2] (IEnumerable`1 source) [0x00000] in <filename unknown>:0 
  at FSharp.CodeFormat.CommentFilter.shrinkOmittedParts (Microsoft.FSharp.Collections.FSharpList`1 source) [0x00000] in <filename unknown>:0 
  at <StartupCode$FSharp-CodeFormat>[email protected] (System.Tuple`2 _arg3) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Control.AsyncBuilderImpl+args@762[System.Tuple`2[Microsoft.FSharp.Compiler.SourceCodeServices+TypeCheckInfo,Microsoft.FSharp.Compiler.SourceCodeServices+ErrorInfo[]],System.Tuple`2[Microsoft.FSharp.Collections.FSharpList`1[FSharp.CodeFormat.Snippet],FSharp.CodeFormat.SourceError[]]].Invoke (System.Tuple`2 a) [0x00000] in <filename unknown>:0 
  --- End of inner exception stack trace ---
  at FSharp.CodeFormat.CodeFormatAgent.ParseSource (System.String file, System.String source, Microsoft.FSharp.Core.FSharpOption`1 options, Microsoft.FSharp.Core.FSharpOption`1 defines) [0x00000] in <filename unknown>:0 
  at FSI_0001.FSharp.Literate.SourceProcessors.processScriptFile (FSI_0001.FSharp.Literate.ProcessingContext ctx, System.String file, System.String output) [0x00000] in <filename unknown>:0 
  at <StartupCode$FSI_0001>[email protected] (FSI_0001.FSharp.Literate.ProcessingContext ctx, System.String file, System.String output) [0x00000] in <filename unknown>:0 
  at Microsoft.FSharp.Core.FSharpFunc`2[FSI_0001.FSharp.Literate.SourceProcessors+ProcessingContext,System.String].InvokeFast[String,Unit] (Microsoft.FSharp.Core.FSharpFunc`2 func, FSI_0001.FSharp.Literate.ProcessingContext arg1, System.String arg2, System.String arg3) [0x00000] in <filename unknown>:0 
  at <StartupCode$FSI_0001>.$FSI_0001_Literate$fsx.processDirectory@577 (FSI_0001.FSharp.Literate.ProcessingContext ctx, System.String indir, System.String outdir) [0x00000] in <filename unknown>:0 
  at FSI_0001.FSharp.Literate.Literate.ProcessDirectory (System.String inputDirectory, System.String templateFile, Microsoft.FSharp.Core.FSharpOption`1 outputDirectory, Microsoft.FSharp.Core.FSharpOption`1 fsharpCompiler, Microsoft.FSharp.Core.FSharpOption`1 prefix, Microsoft.FSharp.Core.FSharpOption`1 compilerOptions, Microsoft.FSharp.Core.FSharpOption`1 lineNumbers, Microsoft.FSharp.Core.FSharpOption`1 references, Microsoft.FSharp.Core.FSharpOption`1 replacements) [0x00000] in <filename unknown>:0 
  at FSI_0002.generateDocs () [0x00000] in <filename unknown>:0 
  at <StartupCode$FSI_0002>.$FSI_0002.main@ () [0x00000] in <filename unknown>:0 
  at (wrapper managed-to-native) System.Reflection.MonoMethod:InternalInvoke (System.Reflection.MonoMethod,object,object[],System.Exception&)
  at System.Reflection.MonoMethod.Invoke (System.Object obj, BindingFlags invokeAttr, System.Reflection.Binder binder, System.Object[] parameters, System.Globalization.CultureInfo culture) [0x00000] in <filename unknown>:0 
Stopped due to error
~/c/FSharp.Formatting git:master ❯❯❯ 

Retrieving evaluated values

I'm looking for a way to know contents of values. For example, I'd like to do like the following.

Input:

(*** hide ***)
let pi = System.Math.PI

(**
The ratio of a circle's circumference to its diameter is about [[[pi]]]...
*)

Output:

The ratio of a circle's circumference to its diameter is about 3.141592654...

Is it possible, or any future plans?

System.NullReferenceException

While running Fsharp.Formating against suave.dll [https://github.com/SuaveIO/suave] the following exception is thrown.

System.NullReferenceException was unhandled
  HResult=-2147467261
  Message=Object reference not set to an instance of an object.
  Source=FSharp.PowerPack.Metadata
  StackTrace:
       at Microsoft.FSharp.Metadata.Reader.Internal.AbstractIL.IL.ILAssemblyRef.FromAssembly(Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\il.fs:line 222
       at Microsoft.FSharp.Metadata.AssemblyLoader.TryAdd(String name, Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 261
       at Microsoft.FSharp.Metadata.AssemblyLoader.TryLoad(String name) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 242
       at <StartupCode$FSharp-PowerPack-Metadata>[email protected](String nm) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 298
       at [e-mail](CcuThunk reqd) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\pickle.fs:line 34
       at Microsoft.FSharp.Primitives.Basics.List.iter[T](FSharpFunc`2 f, FSharpList`1 x)
       at Microsoft.FSharp.Collections.ListModule.Iterate[T](FSharpFunc`2 action, FSharpList`1 list)
       at Microsoft.FSharp.Metadata.Reader.Internal.Pickle.PickledDataWithReferences`1.OptionalFixup(FSharpFunc`2 loader) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\pickle.fs:line 32
       at Microsoft.FSharp.Metadata.AssemblyLoader.TryAdd(String name, Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 298
       at Microsoft.FSharp.Metadata.AssemblyLoader.Add(String name, Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 256
       at Microsoft.FSharp.Metadata.AssemblyLoader.Get(Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 253
       at Microsoft.FSharp.Metadata.FSharpAssembly.FromAssembly(Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 309
       at Microsoft.FSharp.Metadata.FSharpAssembly.FromFile(String fileName) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 314
       at FSharp.MetadataFormat.MetadataFormat.Generate[a,b](String dllFile, String outDir, IEnumerable`1 layoutRoots, FSharpOption`1 parameters, FSharpOption`1 namespaceTemplate, FSharpOption`1 moduleTemplate, FSharpOption`1 typeTemplate, FSharpOption`1 xmlFile) in c:\Tomas\Projects\FSharp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 567
       at Program.generate[a](a _arg1) in C:\Users\ademar\Documents\suave\Documentation\Program.fs:line 11
       at Program.main(String[] argv) in C:\Users\ademar\Documents\suave\Documentation\Program.fs:line 19

this is the program code

open FSharp.MetadataFormat
open System.IO

let root = @"C:\Users\ademar\Documents\suave"

let generate _ = 
    MetadataFormat.Generate
        ( Path.Combine(root, @"Suave\bin\Debug\suave.dll"), 
        Path.Combine(root, @"Documentation\output"),
        [ Path.Combine(root, @"tools\documentation\templates") ] )

[<EntryPoint>]
let main argv = 
    generate ()
    0 // return an integer exit code

Allow to exclude modules/functions/types from the API docs

There are a couple of modules/functions/types which should not be included in the public API docs.

How can I exclude them?

Render line numbers

Hi,

this:

made me think: line no. would be cool.

Build error on teamcity

Hi,

I'm traying to put the use the MetadatFormat.Generate function on teamcity (see http://teamcity.codebetter.com/viewLog.html?buildId=87568&buildTypeId=bt166&tab=buildLog) but I get:

Running build failed.
[12:24:00][Step 2/2] Error:
[12:24:00][Step 2/2] System.TypeInitializationException: The type initializer for 'Microsoft.FSharp.Metadata.AssemblyLoader' threw an exception. ---> System.TypeInitializationException: The type initializer for '<StartupCode$FSharp-PowerPack-Metadata>.$Metadata' threw an exception. ---> System.ArgumentException: could not produce an FSharpAssembly object for the assembly 'FSharp.Core' because this is not an F# assembly
[12:24:00][Step 2/2] Parameter name: name
[12:24:00][Step 2/2] at Microsoft.FSharp.Core.Operators.Raise[T](Exception exn)
[12:24:00][Step 2/2] at Microsoft.FSharp.Metadata.AssemblyLoader.Add(String name, Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 257
[12:24:00][Step 2/2] at <StartupCode$FSharp-PowerPack-Metadata>.$Metadata..cctor() in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 191
[12:24:00][Step 2/2] --- End of inner exception stack trace ---
[12:24:00][Step 2/2] at Microsoft.FSharp.Metadata.AssemblyLoader..cctor() in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 0
[12:24:00][Step 2/2] --- End of inner exception stack trace ---
[12:24:00][Step 2/2] at Microsoft.FSharp.Metadata.AssemblyLoader.Get(Assembly assembly)
[12:24:00][Step 2/2] at Microsoft.FSharp.Metadata.FSharpAssembly.FromAssembly(Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 309
[12:24:00][Step 2/2] at Microsoft.FSharp.Metadata.FSharpAssembly.FromFile(String fileName) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 314
[12:24:00][Step 2/2] at FSharp.MetadataFormat.MetadataFormat.Generate(String dllFile, String outDir, String layoutRoot, FSharpOption1 namespaceTemplate, FSharpOption1 moduleTemplate, FSharpOption1 typeTemplate, FSharpOption1 xmlFile) in c:\dev\FSharp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 586
[12:24:00][Step 2/2] at [email protected](Unit _arg5) in D:\BuildAgent-01\work\aa3eed2981961aa\build.fsx:line 115
[12:24:00][Step 2/2] at Fake.TargetHelper.runTarget@259(String targetName) in D:\BuildAgent-01\work\aa3eed2981961aa\src\app\FakeLib\TargetHelper.fs:line 270
[12:24:00][Step 2/2] System.TypeInitializationException: The type initializer for 'Microsoft.FSharp.Metadata.AssemblyLoader' threw an exception. ---> System.TypeInitializationException: The type initializer for '<StartupCode$FSharp-PowerPack-Metadata>.$Metadata' threw an exception. ---> System.ArgumentException: could not produce an FSharpAssembly object for the assembly 'FSharp.Core' because this is not an F# assembly
[12:24:00][Step 2/2] Parameter name: name
[12:24:00][Step 2/2] at Microsoft.FSharp.Core.Operators.Raise[T](Exception exn)
[12:24:00][Step 2/2] at Microsoft.FSharp.Metadata.AssemblyLoader.Add(String name, Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 257
[12:24:00][Step 2/2] at <StartupCode$FSharp-PowerPack-Metadata>.$Metadata..cctor() in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 191
[12:24:00][Step 2/2] --- End of inner exception stack trace ---
[12:24:00][Step 2/2] at Microsoft.FSharp.Metadata.AssemblyLoader..cctor() in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 0
[12:24:00][Step 2/2] --- End of inner exception stack trace ---
[12:24:00][Step 2/2] at Microsoft.FSharp.Metadata.AssemblyLoader.Get(Assembly assembly)
[12:24:00][Step 2/2] at Microsoft.FSharp.Metadata.FSharpAssembly.FromAssembly(Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 309
[12:24:00][Step 2/2] at Microsoft.FSharp.Metadata.FSharpAssembly.FromFile(String fileName) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 314
[12:24:00][Step 2/2] at FSharp.MetadataFormat.MetadataFormat.Generate(String dllFile, String outDir, String layoutRoot, FSharpOption1 namespaceTemplate, FSharpOption1 moduleTemplate, FSharpOption1 typeTemplate, FSharpOption1 xmlFile) in c:\dev\FSharp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 586
[12:24:00][Step 2/2] at [email protected](Unit _arg5) in D:\BuildAgent-01\work\aa3eed2981961aa\build.fsx:line 115
[12:24:00][Step 2/2] at Fake.TargetHelper.runTarget@259(String targetName) in D:\BuildAgent-01\work\aa3eed2981961aa\src\app\FakeLib\TargetHelper.fs:line 270
[12:24:00][Step 2/2] ##teamcity[buildStatus status='FAILURE' text='System.TypeInitializationException: The type initializer for |'Microsoft.FSharp.Metadata.AssemblyLoader|' threw an exception. ---> System.TypeInitializationException: The type initializer for |'<StartupCode$FSharp-PowerPack-Metadata>.$Metadata|' threw an exception. ---> System.ArgumentException: could not produce an FSharpAssembly object for the assembly |'FSharp.Core|' because this is not an F# assemblyParameter name: name at Microsoft.FSharp.Core.Operators.Raise|[T|](Exception exn) at Microsoft.FSharp.Metadata.AssemblyLoader.Add(String name, Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 257 at <StartupCode$FSharp-PowerPack-Metadata>.$Metadata..cctor() in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 191 --- End of inner exception stack trace --- at Microsoft.FSharp.Metadata.AssemblyLoader..cctor() in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 0 --- End of inner exception stack trace --- at Microsoft.FSharp.Metadata.AssemblyLoader.Get(Assembly assembly) at Microsoft.FSharp.Metadata.FSharpAssembly.FromAssembly(Assembly assembly) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 309 at Microsoft.FSharp.Metadata.FSharpAssembly.FromFile(String fileName) in C:\dev\FSharp.PowerPack\src\FSharp.PowerPack.Metadata\Metadata.fs:line 314 at FSharp.MetadataFormat.MetadataFormat.Generate(String dllFile, String outDir, String layoutRoot, FSharpOption1 namespaceTemplate, FSharpOption1 moduleTemplate, FSharpOption1 typeTemplate, FSharpOption1 xmlFile) in c:\dev\FSharp.Formatting\src\FSharp.MetadataFormat\Main.fs:line 586 at [email protected](Unit _arg5) in D:\BuildAgent-01\work\aa3eed2981961aa\build.fsx:line 115 at Fake.TargetHelper.runTarget@259(String targetName) in D:\BuildAgent-01\work\aa3eed2981961aa\src\app\FakeLib\TargetHelper.fs:line 270']
[12:24:00][Step 2/2]

I works locally on my machine.

Any ideas?

Keep ids in generated html constant if possible

Hi,

I use gh-pages workflow which commits all generated docs into the gh-pages branch. Every commit looks like this

Detect mutable values and show this in tool tip

Hi,

I have a mutable value (I know..):

but this information gets lost:

Cheers,
Steffen

Types inside of modules are not rendered

Hi,

I have some types inside a module:

but somehow they aren't rendered:

Any ideas?

Generate PDF output

Hi Tomas,

I often need PDF documents with F# syntax highlighting. I wonder whether we should generate PDF output directly from the tool.

We can generate a LaTeX document and use pdflatex to produce PDFs. The advantage is that we still can use templates as HTML generation. Its problem is the dependency on an external tool. However, unless we want to be something like pandoc, manipulating PDF on our own is not a good idea.

If we follow the LaTeX route, I would use listings package to color F# code. Tooltips make less sense in PDF format, but using pdfcomment we are still able to see them in Acrobat Reader.

If you agree this is reasonable thing to do, I will try to come up with a pull request.

Support Docco style literate code

It would be great if you could generate Docco style literate formatting of code. I know you can already use the fsx generator on fs files but it would be great to have this option. marginalia is a clojure example which also supports mathjax which would be another great feature.

Allow to embed the output of the F# code

In addition to calling the compiler to get the sytnax highlighting and tooltips, it would be great to have an option to also execute that code and include the output in the generated html. That would make writing tutorials nicer

Is it possible to include inherited members?

In FSharp.Data we have CsvFile inheriting from Runtime.CsvFile<>, and most of the funcionality is in Runtime.CsvFile<>, even though it's hidden. Would be nice to the members of inherited members that are ommited

Update CSS template for literate script

The current one does not handle line numbers correctly.

F# snippets web site link is incorrect in ReadMe

it's pointing to http://wwww.fssnip.net/ instead of http://www.fssnip.net/

Something is wrong with Properties property in Razor

#64 (comment)

Problem when rendering type hints in API docs

Hi,

I have some type hints in FAKE:

it is rendered as:

Cheers,
Steffen

fsharp code snippet in .md file

I am not sure why this change breaks the build script. it only adds a fsharp snippet in a md file.

Based on the documentation here, it should be ok..

Improve tooltips in the presence of <sumary> and other tags

It would be nice to omit the <summary> and <param> elements and just render their content