Back to Questions
7.5k
views9
comments
What is the best F#-aware API documentation tool?
f#fsdocif-docdocs

Hi everyone,

What do you use to produce F# API documentation? Is the niche occupied, or are you interested in a better tool than those that exist already? What would be some of the requirements?

I am currently reviewing a project we had started a few years ago and have not kept updated called if-doc. The basic need is building easy-to-use API documentation for F# project, in particular we want to automate API documentation builds for WebSharper. There are tools like SandCastle but I found it quite unwieldy; in addition, we want first-class support for F# constructs in the documentation (records, unions, lambda functions, modules, and so on).

if-doc (source available at bitbucket) came a long way towards this goal but it requires some work, which I am now considering putting into it. In particular, some of the features I would like to see:

  • Pleasant and modern default theme
  • Single-page HTML5 output
  • Thorough indexing implementation with permalinks
  • Support for JavaScript-based indexing and search
  • Support for combining XML comment-based API docs with a book/tutorial-style documentation
  • Bonus points for allowing to use Markdown to write docs
  • Bonus points for allowing math formulas
  • Easy to use API to use from MSBuild and FAKE
  • Multiple improvements to the apistack.net site that provides the tool as a service; in particular we want to be able to submit NuGet packages / package IDs to the site and make it build documentation

That is a lot of work but having a good doc tool can be a great help for the F# community. I am trying to gauge the interest at this point, and I would very much appreciate your feedback. In particular, if there is a good tool already I do not know about, I would rather use and contribute to that than develop internally.

Also, if you have tried it, you might have noticed that if-doc comes under a restrictive copy-left license. Has this in any way affected you? Deterred from using or contributing to the project? If this is a substantial problem, I can try to lobby for releasing it under the Apache license.

Thanks,

Anton

.

I created Focco (example) to address this, but I would recommend, and plan to begin using, Tomas's FSharp.Formatting project, which includes a literate programming model. I like the generated format much better than Focco's, and Tomas incorporated the F# syntax highlighting, which I never got around to doing.

By on 3/8/2013 8:18 AM ()

On a parallel note, we are working on a literate programming concept for CloudSharper (one of the last bits before we release the beta finally), and FSharp.Formatting could be a great tool to use for this. The idea is simple: putting documentation inside .fsd files which may in turn contain checked/analyzed code blocks. Anyone has further ideas to develop for this?

By on 3/8/2013 9:25 AM ()

FSharp.Formatting looks pretty good! (I think you need to fix the link though). With Focco, is there a URL with example docs it produces?

I still think though that the LP-style documentation cannot entirely replace the need for API docs, though it definitely can complement it and make it a lot nicer. To make API-style docs, tools like `if-doc` reflect assemblies and analyze type structure. Then on the output you get something like this: FSharp.Core @ apistack.net

By on 3/8/2013 8:43 AM ()

I suppose API docs are nice, but I avoid them in favor of blogs, tutorials, etc., so I also don't generate them. I typically find other forms of documentation much easier to consume. That said, API docs are nice for IntelliSense.

By on 3/8/2013 9:31 AM ()

Very interesting, I actually like Focco a lot. Brave design decision :)

Concerning API docs - you are right of course. API docs are not documentation, they are more in the reference role - and yes, IntelliSense fullfills that need mostly. But our customers regularly request API docs for WebSharper. And I myself like to structure code in .FSI with documented FSI files so as to look at them, especially when trying to remember how to deal with a library I used a long time ago.

My favorite doc system is used by Racket (it does not look very nice, but it is very usable). They manage to combine tutorial/book/LP exposition with API reference & search.

I think in the end I will give if-doc another shot, primarily to do a facelift and introduce search. Then I will also look into integrating LP-style doc build into the same process if-doc uses - maybe even using FF or Focco directly.

By on 3/8/2013 9:43 AM ()

Hi Anton,
If Ryan did not mention it already, I would definitely write about F# Formatting - the right link is [link:github.com] It is pretty good for writing tutorial-style articles using Markdown (and it is pretty extensible, so you can work with the parsed documents in different ways, add various pre-processing steps etc.) For example, if there was an API docs, it should be fairly easy to cross-reference that from generated tutorials.

I wanted this mainly for F# Data and for type-providers, the documentation generated from the API (and XML comments) does not make much sense :-), so that is missing.

However, it would be really great if it could also generate documentation for APIs (perhaps by parsing Markdown written in /// comments, instead of using the ugly XML format), so if you were interested in collaborating, I would be very keen to include that (and we could move it under fsharp organization) - but equally, you're welcome to use the standalone tools from F# Formatting in your project.

As I said elsewhere, I would not contribute to a copy-left licensed code - F# Formatting is already used in places where (A)GPL-like license would be a problem (including Microsoft). I think it would be very cool to join the two projects if you were able to use Apache.

By on 3/8/2013 5:23 PM ()

Thanks Tomas! I needed to hear this again, I now can use your feedback to keep lobbying for Apache-licensing if-doc. Whether that succeeds or not, it sounds like I have a go for putting some more time into it, so Markdown-style documentation inside '///' comments is now on the list of things to add to if-doc.

By on 3/11/2013 8:38 AM ()

Very interesting, I actually like Focco a lot. Brave design decision :)

I wish I could take the credit, but it is merely a rip-off of the docco project. :) Most of the issues have been outstanding for a year or more, mostly because I focused on other things and then found FSharp.Formatting. I would actually suggest you use FF and perhaps use the template from Focco, updating accordingly to match to the template syntax used by FSharp.Formatting.

By on 3/8/2013 10:04 AM ()

I just added the link to the current (actually, out-of-date) Frank docs and fixed the link to FSharp.Formatting. Thanks!

By on 3/8/2013 9:29 AM ()

    Topic tags

    IntelliFactory Offices Copyright (c) 2011-2012 IntelliFactory. All rights reserved.
    Home | Products | Consulting | Trainings | Blogs | Jobs | Contact Us | Terms of Use | Privacy Policy | Cookie Policy     		Built with WebSharper