Haddock documentation layout improvements

[brendanhay]

When viewing the main entry-point to RIO on Hackage/Stackage, you see a Documentation heading and then you're straight into Utf8Builder, Display, etc. Looking at the right-side contents menu, we see Standard logging functions, Run with logging, and so on:

Now, If I was perhaps looking for the penultimate RIO newtype - I would peruse the contents menu and see .. nothing? Hmm.

So Ctrl-F still seems to work in Netscape Navigator and searching for "newtype RIO" yields the following:

Wat.

What follows is highly personal preference/opinion/bias, but hopefully constructive:

1. Even if your project has a great README, which RIO most certainly does, it's still nice to have a brief introduction full of linked-Hackage identifiers I can click on to get places quickly in the heading of the RIO module documentation. Doesn't need to be in every leaf module, probably just RIO.

2. The right contents menu needs more focus on high-level concepts as main headings, with sub-headings to drill down as deemed necessary/useful. Imagine mirroring how a dead-tree technical reference organises its table of contents.

Example:

• The RIO Monad (not-a-transformer)
• Containers
• State, Writer, and Mutable References
• Logging
  • Options
  • Advanced Logging
  • Textual Output
• Displaying Datatypes

There's alot of top-level headings such as Text, and Display that then only group logging related functions - the Display type class is not under its respective heading.

3. All whenM, nubOrd, view, etc. functions are just sort of 'exported'. I tend to still think of things in terms of their 'classic' namespaces - ie. Control -> Control.Monad -> when/M - I understand people new to Haskell probably don't have this baggage, but still grouping things similarly in terms of headings/exports lets people see what the analogies are with pre-existing base, preludes, and so on. List things go under a List heading, Either under Either, writeFile and so on under Monad/Unlift/IO, and so forth.

4. Lenses. These probably deserve their own section.

5. Typeclasses. Probably coincides with 3. - the type classes and related functions should be grouped under respective headings, whether they be top-level NFData, Applicative, etc. or under Control-esque headings - ordering somewhat according a heirarchy, ala Functor -> Applicative -> Monad.

[snoyberg]

CC @lehins

[lehins]

@brendanhay Thank you for raising this issue. I promise, there is a perfect explanation for the current structure of the documentation. All of the modules and functions are exported in alphabetical order ;)

I took a stab at initial improvement to the documentation in this PR: #163 Please, take a look at it see if you have any comments or suggestions. We can improve on it in the future, with more examples and better instructions, but for now I at least wanted to organize the haddock into a usable state.

cc @snoyberg I'll wait for your feedback on this PR.

[snoyberg]

PR has been merged and released, thanks @lehins!

[brendanhay]

New Haddocks look great! :ok_man: