Implement fsdoc

[sishtiaq]

https://github.com/FStarLang/FStar/wiki/Generating-documentation-with-fsdoc-comments

Work items:

• write out an index.mk. Done with 9f0cfb7def1e112331a40c4fc1c775039fe4ffcc.
• Comments: on empty line
• Comments: top-level declarations: type
• Comments: top-level declarations: val
• Comments: top-level declarations: let
• Comments: top-level declarations: module decl
• Comments: finer than top-level declarations: {fields, algerbraic type variants, mutually rec decls}
• Implement keywords: inline,
• Implement keywords: omit
• Implement keywords: summary
• x-ref

[markulf]

Could we add an example .md to the wiki? If it looks nice more people might pick it up.

[msprotz]

Just chatted with @vkanne-msft and the plan is to generate documentation nightly and put it up on fstarlang.github.io/doc ... will motive people more I think!

[markulf]

+1

[sishtiaq]

Commit 33e14b9 implements

• write out an index.md.
• Comments: on empty line
• Comments: top-level declarations: type
• Comments: top-level declarations: val
• Comments: top-level declarations: let
• Comments: top-level declarations: module decl
• Comments: finer than top-level declarations: {fields, algerbraic type variants, mutually rec decls}.

[msprotz]

Additional feature requests:

• run pandoc --standalone --css=style.css

The index seems to have --standalone but not --css; individual module pages seem to have neither.

Thanks,

Jonathan

[sishtiaq]

Fixed -s and --css in 81aa0d2.

[sishtiaq]

I intend to close this issue soon, and replace it with a new one to track the last four items of work:

• Implement keywords: inline,
• Implement keywords: omit
• Implement keywords: summary
• x-ref

The first three will be quick; the last might take longer (especially if we don't want to build yet another dependency analyzer inside the F* compiler).

[markulf]

We need some push to convert normal comments to fsdoc comments. Currently
https://fstarlang.github.io/docs/ is quite sad, with only FStar.List being properly documented.

[aseemr]

Since fsdoc is removed in favor of fstardoc (#1939 ), closing this issue.