Ticket #70 (new enhancement)

Opened 6 years ago

Last modified 2 years ago

'Contents' improvements based on Python's docs

Reported by: crutcher@… Owned by:
Priority: major Milestone:
Version: Keywords:
Cc: SamB

Description

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.

Change History

  Changed 6 years ago by waern

  • milestone changed from 2.5.0 to 2.6.0

follow-up: ↓ 4   Changed 6 years ago by SamB

  • priority changed from major to critical

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

  Changed 6 years ago by SamB

  • cc SamB added

in reply to: ↑ 2   Changed 6 years ago by waern

  • priority changed from critical to major

Replying to 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.

  Changed 2 years ago by anonymous

  • milestone 2.6.0 deleted

Milestone 2.6.0 deleted

Note: See TracTickets for help on using tickets.