Replies: 8 comments
-
|
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 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.
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.
Docs on fsharp.org. I don't have strong opinions about this.
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. |
Beta Was this translation helpful? Give feedback.
-
|
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:
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. |
Beta Was this translation helpful? Give feedback.
-
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:
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. |
Beta Was this translation helpful? Give feedback.
-
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 :-) |
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
-
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 |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
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 |
Beta Was this translation helpful? Give feedback.
-
Continuing discussion from #27
Beta Was this translation helpful? Give feedback.
All reactions