Fp-ts: How and where do you want to add docs

[davetayls]

I'm happy to help with adding docs to the project, how would you like them to be structured?

[gcanti]

That would be great, thanks. Actually I don't know, I'm definitely open to suggestions.

[davetayls]

I could just start a docs folder and have a md file for each

[SimonMeskens]

How are you handling the code documentation @davetayls? Seems like being able to hover over a method and getting the docs is a pretty important part of docs. Or are these more usage guides instead of API docs?

[davetayls]

I guess I had more usage guides in mind but thorough enough to explain the
methods and functions available.

If we were to write jsdoc style docs on each of the functions that would be
really useful for IDEs, I hadn't considered that.

[SimonMeskens]

I'd be willing to work on jsdocs to go along with the usage guides. What kind of input would you like? JSON or markdown? I could write commits for the jsdocs and have an exporter generate the format you like? I'm thinking the docs could be in "chapters" per source file, starting with a usage guide and then more straightforward API doc exported from jsdocs?

[gcanti]

I would expect to extract the API docs from type annotations instead of jsdoc. Here's a tool that can be helpful http://typedoc.org/guides/doccomments/

[davetayls]

That sounds like a good place to start then. Let's work out the best way of
using that tool

[SimonMeskens]

Okay, looked into this one. Basically, we want to export .md files to the /docs/api/ folder and then set docs as our GitHub Page. That will let us automatically publish the API to web page through Jekyll.

This Jekyll page could contain other info, like the book branch eventually or small guides as @davetayls wants to add for each class. That's also why I'd publish to an /api/ subfolder. I've done some Jekyll websites, it's quite easy to setup.

What's also needed is a setup that will generate these markdown files, I think Typedoc can do this. Once the whole setup is done, it's just a question of PRing in jsdocs and other documentation.

[SimonMeskens]

Example: https://github.com/TypeStrong/typedoc-site

Notice that the typedoc output is under /api/

We would have a similar setup under /docs/ (so we don't need to add and update a gh-pages branch or second repository)

[davetayls]

That sounds like a plan, let's start with the typedoc comments. I'll remove my branch for the moment and we can just add those first as they will be immediately useful

[davetayls]

There seems to be a number of ways in which the code in this library can be imported and used. should we be suggesting a particular pattern?

ie

import Option from 'fp-ts/lib/Option`

or

import {fromNullable} from 'fp-ts/lib/Option'

[raveclassic]

@gcanti I'm watching the repo and new commits. An _insane_ amount of useful stuff, can't wait for the docs and _more_ examples!

@davetayls Personally I'm against default imports/exports and IMO they should be avoided.
Firstly default import can be inconsistent with default export, because if you change export of a module to some other semantically different thing, consuming module won't be notified. Like you exported default banana and imported it in gorilla module. But then you export default large hadron collider but gorilla still imports it as a banana.
Secondly (which is more important IMO) autoimports don't work. Start using them and you can't live without them.

[gcanti]

can't wait for the docs and more examples!

As a new example I'm writing a porting of https://github.com/slamdata/purescript-routing (I'm curious whether the PureScript's applicative syntax can be translated to TypeScript in a handy way).

@raveclassic Anyway I'm open to suggestions, if you stumble upon a good example (even in other languages) let me know

[gcanti]

FYI the new example is here https://github.com/gcanti/fp-ts-routing

[raveclassic]

I've opened #227 with basic typedoc autogeneration. Github pages can be enabled in the settings of this repo by @gcanti so that this documentation is autohosted at https://gcanti.github.io/fp-ts. Doc generation should be manually run _after_ release with a tag. It picks up revision hashcode of the latest tag found on master branch so that docs include links to proper version of the code.

[gcanti]

Opened https://github.com/gcanti/fp-ts/pull/237

The template is loosely inspired by pursuit, let me know what you think.

/cc @OliverJAsh @justinwoo

[raveclassic]

@gcanti As #237 is merged, should we close this issue? There's #265 tracking examples in documentation.