search

ku-fpg / hermit-shell

HERMIT with GHCi shell
BSD 3-Clause "New" or "Revised" License
2 stars 0 forks source link

Documentation in the new `External` class #10

Closed ecaustin closed 9 years ago

ecaustin commented 9 years ago

Are we planning to do anything with the documentation portion of the external values for the server? The external method as currently written ignores it, but I wasn't sure if the future plan was to mimic the old shell's help functionality.

The reason I ask is that the HERMIT.Server.Parser.Transform module is a 1k+ line eyesore that I would like to clean up in any way possible.

Unfortunately, because External is a type family, using hs-boot files to separate the instances into their own files is a non-starter.

ecaustin commented 9 years ago

Brought up in ongoing debate for issue https://github.com/ku-fpg/hermit-shell/issues/21.

The current consensus is to keep the documentation around in the short-term.

RyanGlScott commented 9 years ago

For documentation, one possibility is using Hoogle. We already have the HERMIT documentation for each command embedded as a Haddock comment in the source code, so installing the Hoogle indexes for hermit-shell is a matter of:

cabal install hoogle
cd hermit-shell/
cabal haddock --hoogle
hoogle convert dist/doc/html/hermit-shell/index.html ~/.cabal/share/x86_64-linux-ghc-7.10.1/hoogle-4.2.41/databases/hoogle.hoo

module some directory names and version numbers. We have hermit-shell make an alias (:doc) aliased in GHCi to look up the Haddock comments for any command, so :doc rhsOf would be akin to help rhs-of in hermit.

Of course, the above process needs to be automated a lot more. I'll throw together a script for doing this at some point. For a more robust solution, the hoogle-index library looks like it could do what we need, if it were modified some. I've submitted an issue about adding the ability to index a single package only from hoogle-index.