'Contents' improvements based on Python's docs

[ghc-mirror]

Original reporter: crutcher@

Contrasting this page: http://haskell.org/ghc/docs/latest/html/libraries/

With this one: http://docs.python.org/library/index.html

We can see a number of ways to improve the library listings for haddock contents.

First, there descriptions given to the libraries, rather than just their names.

Second, the libraries themselves are grouped into type groups, above and beyond the lib paths themselves.

Third, when you actually drill into a page a 'breadcrumb' is placed at the top of the page for navigating back out. Example, clicking on 'array' yields a page headed with:
Python v2.6.1 documentation » The Python Standard Library » Data Types »

These are 3 links, each stepping back up to a different containing level.

[ghc-mirror]

Original reporter: naesten@

Well, it seems like the first thing we need is a syntax for the short descriptions to show in the 'Contents'.

[ghc-mirror]

Original reporter: david.waern@

Replying to [comment:2 SamB]:

Well, it seems like the first thing we need is a syntax for the short descriptions to show in the 'Contents'.

Perhaps a "Brief" field could be added to the module header. For some modules it would be really useful to be able to see a brief description in the contents page. For modules with quite self-explanatory names such a thing would be less meaningful and could then just be omitted by the module author.

Then the question is if we want to group the modules for a better overview, and if so, how we should do that. Possible ways to group the modules: by package, by root namespace (Control, Data, etc), and by Cabal category (as done on Hackage).

I'm lowering the priority since I don't think this is critical, although it's very important that we improve the contents page. I agree that there's a big difference between the python page and ours.

Better navigation features, like "breadcrumbs" for instance, should be made into separate tickets, IMO.