Docfx: Questions about DocFX support for F# and ways to contribute

[bentayloruk]

With this issue, I'm hoping to start a conversation about F# support in DocFX and how best to contribute where possible. I'm successfully using DocFX 2.40.4 on macOS (via Brew) to generate documentation for an F# project (big thanks to @surban for the PRs that made this happen). However, there are things I'd like to tweak and change, but I'm unsure whether F# has a solid future with DocFX. If it does, I'm not sure which version to contribute to.

One of the main issues I have currently, is that I have an OO public API, written in F#, that I'd like to generate C# style documentation for. It doesn't seem that I can do that. Given that most C# devs are not familiar with F# declaration syntax and actually seem to be put off by it, I'd like to provide a version of the documentation that makes them feel comfortable.

With these observations in mind, I have the following questions:

Will DocFX version 3 support F# as part of the initial release?

• If yes, would "C# style doc generation for F# libraries" be part of V3 too or is it something that would be welcomed as a contribution?
• If no:
  
  
  
  • Are there plans to add F# support to V3 or will it need to come from the community?
  
  
  • Does DocFX version 2.x likely have a long life? Is it worth contributing large-ish features to V2?
  
  

Appreciate any thoughts or answers you all might have! Thanks.

[superyyrrzz]

@bentayloruk Thank you for your feedback. In short, welcome to contribute to v2.

Will DocFX version 3 support F# as part of the initial release?

I'm afraid not. Currently, DocFX v3 still focuses on building Markdown files into a docs.microsoft.com like site. Even the design of C# support is in early stage. However, we know your feedback and we can take it into consideration.

Are there plans to add F# support to V3 or will it need to come from the community?

Maybe from community. We lack F# expects in teams :)

Does DocFX version 2.x likely have a long life? Is it worth contributing large-ish features to V2?

As v3 will not be ready to release with equivalent features as v2 in a near future, v2 will still remain the main version to use. If you want this feature in your current work, v2 will be the right place to contribute currently.

[bentayloruk]

In short, welcome to contribute to v2.

Great, thanks for the clarification.

Even the design of C# support is in early stage. However, we know your feedback and we can take it into consideration.

👍

Maybe from community. We lack F# expects in teams :)

What would be the best way for the F# community to make sure F# can be a first class citizen with V3? Could we look at the C# support design for V3 and give an F# perspective on it? Is the design public somewhere?

[superyyrrzz]

We still have no design doc for C# support, but the rough idea is to leverage monodoc to extract information into JSON/YAML, and use DocFX to built it into a site. The good news is that I find monodoc supports F#, so maybe this flow can work for F# without too much cost. Of course it need more investigation.

We do want to hear voice from community. We will involve you when designing these features.

[bentayloruk]

We do want to hear voice from community. We will involve you when designing these features.

This would be great, thank you.

[superyyrrzz]

@TianqiZhang to aware of this issue.

After migrating MREF to SDP, the YAML files should be valid input to both v2 and v3. Your tool to generate SDP YAMLs could be part of DocFX v3, as the metadata command in v2. Maybe it can support F# as mdoc supports it.

[Kavignon]

@bentayloruk @superyyrrzz I'm also really interested in this feature! F# would ve great in v3!