F# doc generation discussion

[dsyme]

Continuing discussion from #27

No. Docs is a general term. Frankly I'm not sure what this repo does at this point other than run a tool in CI, but what it emits is very specific: the API reference for FSharp.Core. The repo should be named according to what it does.

fsharp/core-reference
fsharp/core-api-reference
fsharp/api-reference
fsharp/fsharp-core-reference
fsharp/fsharp-core-library-reference

etc.

docs.fsharp.org also doesn't point anywhere.

I think we need to slow down here and assess what it is we're actually trying to accomplish. Taking broad strokes to build and merge and completely change everything without time for feedback that's been asked for shouldn't be done. Is this:

• An FSharp.Core API reference?
• A more general API reference for other things in F#?
• A general documentation site for F# that also includes FSharp.Core, effectively competing with the MS docs?
• A stopgap for when FSharp.Core gets properly ingested into docs.microsoft.com?
• A place for people to make meaningful contributions to the docs site? (see here: Adjust the logo link (was Contribution needs improving) #30)
• An experiment to test FSharp.Formatting?

At this point I'm not clear about it anymore. The original goal was to act as a stopgap to eventually be subsumed by the MS docs site.

[dsyme]

Here's my thinking on where we are:

F# language support for docs. The F# language design and default tools built on FSharp.Compiler.Service should properly support the C# XML doc standard. This includes checking docs at compile time and resolving cref symbols (to allow rename-refactoring to rename the symbols).

Separately we should actively consider putting in support for markdown docs into the core language design and tooling. It should be experimented with as much as feasible on the outside but delivered in the core tooling.

Doc tooling (library): FSharp.Formatting is both a library and a tool. The library side is in fairly good shape but in some areas requires continued iteration (especilly ApiDocs). No one should be picking up a dependency on F#F as a library unless you are building a tool or a very simple API that effectively encapsulates the dependency.

That said, FSharp.Formatting is at the root of the doc-aware universe for F# - just like FSharp.Compiler.Service is at the root of the non-doc-aware universe (note that for API Docs FSharp.Formatting is really a layer over FCS adding doc-awareness).

This means we need to embrace the long term role of F#F and actively improve it, just like we need to embrace the long term rols of FSharp.Compiler.Service and embrace that. I finally forced myself to do this over the last two months, to rip the stinking mess of Razor out of F#F and iterate until it was usable and half-effective in terms of accurate content. I will continue to iterate and engage on that because it's just too important, even for a project like DiffSharp. I believe this may now allow other people to engage at that layer too once the dust settles over the next month or two.

Doc tooling (tool): There is a continuing need for content-driven, stylable, low-dependency tooling that can deliver quality documentation for a typical F# library project with almost no effort. For me, this is how I got into this: I need doc tooling for DiffSharp.

• The basic experience should be "install tool and make me the docs"

• The docs should be built from content (and optionally a template and styling)

• Ideally this should be done without writing any F# scriptsm and avoiding duplicating scripts

• This tooling should generate accurate, bug-free doc content and be good enough to generate quality documentation for FSharp.Core, FSharp.Compiler.Service, FSharp.Data and other projects.

• The default design styling(s) should be excellent. People who are good at design in the community should be actively improving it at its core.

• The literate content should be F# scripts and markdown. The primary outputs for these should be HTML and notebooks.

FSharp.Core docs Currently there are no FSharp.Core docs by Microsoft at all - the old MSDN docs are no longer found by google search. Further, I doubt the long term ability to deliver up-to-date doc content for FSharp.Core given that the documentation is, to my understanding, hand-written. If it happens that's great though it's a shame if the content is not authored in a way that improves doc tooling at its core (e.g. not written using F# language XML doc tooling).

Because of this situation, the FSSF and community should at least have the ability to generate and deliver docs for FSharp.Core. That's what this repo is currently for - to deliver those docs when they are needed and for as long as they are needed.

The doc content in FSharp.Core.xml needs massive improvement. Actually being able to see the generated docs here is a good step and anything that anyone notices about poor content should be noted ASAP.

FSharp.XYZ* ecosystem docs: There is a significant set of community components that have doc presence that needs updating (FSharp.Data, FSharp.Compiler.Service, maybe 5-10 other components). I don't have strong opinions about that except that

1. I never ever want to see another generate.fsx script in my life - that was an unmaintainable way of generating docs
2. The docs should use tooling that is content driven and ultra simple (for long term maintenance)
3. The styling and templating should be magnificent (not something I can do)

Docs on fsharp.org. I don't have strong opinions about this.

• Because of the issues with FSharp.Core docs it seems natural for the FSSF to have the capability to deliver FSharp.Core docs. Using fsharp.github.io/docs seems a reasonable host link for this, fsharp.github.io/fsharp-core-docs would be OK as well. It really depends on whether there is longer term intent to expand to have a unified doc presence for other F# libraries.

• At the last Dugnad a position put forward was fsharp.org should have a searchable docs experience. This seems a reasonable long term goal but it has ramifications and needs discussion.

• Having the technical capability to easily deliver quality API docs from a set of say 10 chosen nuget packages seems like a good thing.

Multi-language docs. We should make sure we keep the capability to deliver multi-language docs. Please advise on what's the best approach to this.

[cartermp]

I think this repo should be strictly about FSharp.Core API reference documentation. Whether or not it eventually gets replaced by the MS docs site can be resolved later, but that was the original scope and I think it should stay that way. A good path forward is to use it as a way to show a great way how to generate it, then work the MS docs owners to incorporate the tools used/built here to generate an API reference in the same way they're ultimately generated here. Since they're entirely OSS this seems tractable.

Regarding this point in the PR:

Please redesign the core F#F template and/or CSS for it. But aim to get that into FSharp.Formatting, so all docs for all sites can make use of it.

I don't think we can apply a "one size fits all" approach here. Styling and layout should be done in a way that is best for the FSharp.Core reference, not all possible F# libraries. I feel flexible on this position, but at the end of the day what matters is that FSharp.Core has a quality reference people can access, not that we solve the problem of how to generate API references for any arbitrary F# codebase.

[dsyme]

at the end of the day what matters is that FSharp.Core has a quality reference people can access

Yes, I do agree with this as the core goal for this repo. However there was no chance of reaching this goal without a thorough revision of F#F. We have to build to build on solid foundations.

F#F is not "one size fits all" - it has always had four levels for styling and customization:

1. Template parameters
2. CSS
3. A bespoke template
4. Use the ApiDocsModel

These involve increasingly more work and are increasingly fragile. I want to actually document these and make them as stable and clear as possible.

As the current effective maintainer on F#F my position is that the library and tool should at least be provably capable of producing quality docs for FSharp.Core without any special settings. If it's not capable of that (in terms of content production, search index and basic styling), then no amount of styling will ever give you what you want - not even reverting to level-4 customization (as this repo was previously doing) would have helped - it was just been building on sand. There is simply no way to work around problems in logical content coming out of F#F except through unmaintainable patch hacks (just as you can't get quality code out of FCS by patching stuff from the outside).

So first we have to get to a point the F#F is giving us the right logical content - based on accurate content in FSharp.Core.xml. Once that is actually in place and fully stable then people can do Level 1-3 customization (styling and templating) as much as they like, and if really necessary even do Level 4 customization too (though it's likely to break over time).

Whether this repo actually ends up using any customization is another thing - I'd prefer not until we're sure we've got the doc model right - but yes, some customization makes sense. But first things first.

[dsyme]

A good path forward is to use it as a way to show a great way how to generate it, then work the MS docs owners to incorporate the tools used/built here to generate an API reference in the same way they're ultimately generated here. Since they're entirely OSS this seems tractable.

It's a good goal. However it's not this repo in isolation. This repo - like any Waypoint or MiniScaffold repos - has always has had a massive dependency on FSharp.Formatting (or at least the FSharp.Formatting.ApiDocs part). We have to get that layer right.

That's a dependency on a component that was, until recently, frankly nowhere near what was needed to do quality doc generation for DiffSharp, FSharp.Core or FSharp.Compiler.Service (the three projects I really care about). It is getting closer now, but there is still much more to do, nearly all of it generic.

In terms of possibly handing off to the MS doc owners - please start a new issue on what might be required, what kind of tooling/demonstration you think they might accept, what kind of internationalization and styling options they might need. If that's one possible end game then we'll need info on what that looks like :-)

[cartermp]

In terms of possibly handing off to the MS doc owners - please start a new issue on what might be required, what kind of tooling/demonstration you think they might accept, what kind of internationalization and styling options they might need. If that's one possible end game then we'll need info on what that looks like :-)

There's little required here. Nearly everything you mention here is not a concern of ours or of FSharp.Formatting. The only one worth focusing on is having the tool emit a reference in the structure and file format that the docs system uses. Everything else is handled by the docs system (styles, localization, ensuring it builds with samples, TOC generation, etc.). This should be something that is focused on once the dust settles a little bit and the core formatting engine for FSharp.Formatting is in a good place.

What the MS docs team requires is a tool that can be pointed at all shipped FSharp.Core NuGet packages and generate a reference that follows the structure and file format they use. Otherwise, the only path forward is to manually migrate the old reference markdown files, fix them up, and add new ones manually every time a new FSharp.Core ships.

It can be negotiated that the reference doesn't go back very far since we can't retroactively ship updates to older packages.

[dsyme]

The only one worth focusing on is having the tool emit a reference in the structure and file format that the docs system uses.

Sounds like FSharp.Formatting is moving in the direction that's needed.

The ApiDocsModel is getting more and more complete (eg parameter information integrated, example sections available) and it just takes 300 lines or so to generate structured HTML following a particular spec, using particular tags. The cross reference links are probably usable already with the right root. Take a look at GenerateHtml.fs in FSF.

Generating the search material (?) and navigation information (?) will also be important, but overall it sounds like programming up a new version of GenerateHtml.fs in FSF to produce the required structure and CSS tags. A spec of those (or use existing sample pages) would be needed but it wouldn't be hard. If they could provide a sample outer template with associated content to trial against that would help, or we could piece it together from the existing pages on docs.microsoft.com

I think it would be a new tool (much like fsdocs, you could fork that) or could be added in as an optional HTML generation option and styling to fsdocs. If have no problem with someone doing that

[dsyme]

Btw have you got the old reference markdown files? I'd like to start copying out the best of the content into the Fscore xml docs if you have it.

[cartermp]

they are here: https://github.com/dotnet/docs/tree/migration-fsharp/docs/fsharp/library-reference

I migrated some of them by hand but it is a very large task and they are quite messy