62 docs generation fsharp formatting

[TheAngryByrd]

Proposed Changes

Adding Documentation Generation

Closes #62

Types of changes

What types of changes does your code introduce to MiniScaffold?
Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.

• Build and tests pass locally
• I have added tests that prove my fix is effective or that my feature works (if appropriate)
• I have added necessary documentation (if appropriate)

Further comments

[TheAngryByrd]

Thanks to @ominestre for a lot of the conversion help!

[TheAngryByrd]

TODO:

• Generate Nav from structure of doc files
• Front matter in general. Metadata being put into head of html
• Type info on detail pages
• Github source lines match up
• Watch/hotreload
• Multiple frameworks (TFMs)

[TheAngryByrd]

@baronfel I have hot reloading for things in docsSrc. Know of a way we can do it for the fsx files under templates since they are needed to be reloaded into the currently running fake script?

[baronfel]

I pushed up some fixes for comments, we had the rendering of them inside an if-expression that was a bit too broad. To clarify the structure of the partMembers function I broke it out into named pieces.

[TheAngryByrd]

Things left to do:

• Generating a Navigation structure from the folder structure
• Good styling / structure of pages
• Dealing with different Target Frameworks (should we care about this?, this isn't a showstopper to me)
• Dealing with multiple (older) versions of the documentation (could be put into a separate issue, this isn't a showstopper to me)

@baronfel @jdodds I think we need to just build a Trie for the nav structure. Then building that into a sub nav dropdown structure with bootstrap.

@andrewpucci I think we're at the point where I'll need your help whenever you get a chance to save me from my design skills.

[andrewpucci]

Looks good to me. There's definitely some cleaning up we can do with the styles, but we can do that in a new issue.

[baronfel]

functionality-wise it's great. I have a couple suggestions/questions around the structure of the templates themselves.

[baronfel]

similarly, I've seen this xmldoc section repeated as well. seems like a good place for a component/function.

[baronfel]

Few things:

header

• should the menus animate on hover, not just click?
  • won't fix

footer

• contributing link isn't shown. Should these links not render if the backing file doesn't exist? https://github.com/TheAngryByrd/miniscaffold-docs-test/blob/master/CONTRIBUTING.md
• same for code of conduct
• The FSSF slack link won't work if you don't have a login, maybe it should point to https://fsharp.org/guides/slack/ instead, which has registration instructions?
• 'edit this page' link can go right to the edit experience if we point to /edit/ instead of /blob/ in the url
• copyright notice doesn't have a date in it, should it be generated with one?

landing page

• it feels like the api-docs button isn't anchored the same as the others. not quite in the bottom-left corner of the box? and should they all be bottom-right instead?
• 'learn usecases' button 404's, currently going to https://www.jimmybyrd.me/miniscaffold-docs-test/HowTos/Doing_A_Thing.html. is that the right url?

Api reference

type-level pages

• the namespace isn't rendered the same as it is in the module-level. There it's a bolded-heading with text underneath, here it's all plain text.
• For unions, do the docs include the field names if the union case fields have names?
  • yes they do

type signatures

• should names of types that are in this library be hyperlinked?
  • won't fix, will require deep dives into FSharp.Formatting