dash-haskell: Command line tool to generate Dash docsets (IDE docs) from package haddock

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Dash is a framework and file format for allowing easy lookup and indexing of programming docs, e.g. API functions and modules. A number of plugins offer dash docset lookup in editors such as Emacs and Vim. By using this tool, one can convert haskell package haddock(s) to docsets.

The major benefit of dash-haskell, is that once these docsets are built, dash tools provide one of the few, if only solutions for offline, contextual, and project dependency approximate IDE documentation for Haskell.

Summary:

$ dash-haskell --help
Usage: dash-haskell [-p|--dbprovider <provider,args>] [-o|--output <dir>]
                    [-q|--quiet] [-c|--cabal <file.cabal>]
                    [-r|--cabal-constraints executable=name, ..] [packages]
  additional help is also available on arguments with "dash-haskell help arg"
Available options:
  -h,--help                Show this help text
  -p,--dbprovider <provider,args>
                           a ghc package db provider: cabal|ghc|dir
  -o,--output <dir>        the directory to write created docsets to
  -q,--quiet               set to quiet output
  -c,--cabal <file.cabal>  the cabal file to source package dependencies from
  -r,--cabal-constraints executable=name, ..
                           limit package results from a cabal file source, see
                           documentation
  packages                 a list of packages to specifically build, e.g.
                           either-1.0.1 text-1.2.0
$ cd foo-1.2.0/
$ dash-haskell -c foo.cabal -o docsets
db provider:
  lookup strategy: cabal sandbox db index
  cmd: cabal
  args: sandbox hc-pkg list

processing: system-filepath-0.4.12
  writing files..
  writing plist..
  populating database..
  finished populating sqlite database..

processing: system-fileio-0.3.14
  writing files..
  writing plist..
  populating database..
  finished populating sqlite database..

processing: pipes-4.1.2
  writing files..
  writing plist..
  populating database..
  finished populating sqlite database..

warning: failed to process: parsec-3.1.5
warning: path errors in pkg conf file:
 /home/jpf/local/cabal-sandboxes/dash-haskell/x86_64-linux-ghc-7.8.3-packages.conf.d/parsec-3.1.5-abf7e89cafe4e74712f678cea843c1c8.conf
with problem(s):
 missing: haddock interface file
 missing: html doc dir

processing: sqlite-simple-0.4.8.0
  writing files..
  writing plist..
  populating database..
  finished populating sqlite database..

$

Notice, the failure of parsec-3.1.5 is illustrated here to show that in this case, dash-haskell depends on haddock documentation being built for the requested package. A possible resolution in this case, if using a sandbox, is:

$ cabal install --reinstall parsec-3.1.5 --enable-documentation
$ dash-haskell parsec-3.1.5 -o docsets

Versions:

The version numbering scheme for this package is defined as follows, given:

dash-haskell-a.b.c.d

a, b index interface or feature changes to the CLI

c, d index bug-fix and documentation updates


[Skip to Readme]

Properties

Versions 1.0.0.0, 1.0.0.1, 1.0.0.2, 1.0.0.2, 1.0.0.3, 1.0.0.4, 1.0.0.5, 1.1.0.0, 1.1.0.1, 1.1.0.2
Change log None available
Dependencies base (>=4.7 && <4.8), bytestring (>=0.10.0.1), Cabal (>=1.18), containers (>=0.5.5.1), direct-sqlite (>=2.3.13), directory (>=1.2.1.0), either (>=4.3), ghc (>=7.8.3), haddock-api (>=2.15.0), mtl (>=2.1.3.1), optparse-applicative (>=0.10.0 && <0.11), parsec (>=3.1.5), pipes (>=4.1.0), process (>=1.2.0.0), sqlite-simple (>=0.4.5.0), system-fileio (>=0.3.12 && <0.3.15), system-filepath (>=0.3.1 && <0.5), tagsoup (>=0.12.7), text (>=0.7.1), transformers (>=0.3 && <0.5) [details]
License LGPL-3.0-only
Copyright (c) 2014 John P. Feltz
Author John P. Feltz
Maintainer jfeltz@gmail.com
Category Documentation
Home page http://www.github.com/jfeltz/dash-haskell
Bug tracker https://github.com/jfeltz/dash-haskell/issues
Uploaded by jfeltz at 2014-10-26T19:47:25Z

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for dash-haskell-1.0.0.2

[back to package description]

dash-haskell

local and approximate package doc access for your Haskell project dependencies

direct to browser lookup: look-up

keyword, module, and package searching: listing

The purpose of the dash-haskell is to facilitate Haskell documentation in IDE(s), with the following qualities:

Summary

  Usage: dash-haskell [-p|--dbprovider <provider,args>] [-o|--output <dir>]
                      [-q|--quiet] [-c|--cabal <file.cabal>]
                      [-r|--cabal-constraints executable=name, ..] [packages]
    additional help is available with "dash-haskell help <topic|option>"

  Available options:
    -h,--help                Show this help text
    -p,--dbprovider <provider,args>
                             a ghc package db provider: cabal|ghc|dir
    -o,--output <dir>        the directory to write created docsets to
    -q,--quiet               set to quiet output
    -c,--cabal <file.cabal>  the cabal file to retrieve package dependencies from 
    -r,--cabal-constraints executable=name, ..
                             limit package results from a cabal file source, see
                             documentation
    packages                 a list of packages to specifically build, e.g.
                             either-1.0.1 text-1.2.0

Usage Example

The following example shows how to use dash-haskell to generate docsets for a cabal sandbox project.

  $ cd foo-1.2.0/ 
  $ dash-haskell -c foo.cabal -o docsets 
  db provider:
    lookup strategy: cabal sandbox db index
    cmd: cabal
    args: sandbox hc-pkg list

  processing: system-filepath-0.4.12
    writing files..
    writing plist..
    populating database..
    finished populating sqlite database..

  processing: system-fileio-0.3.14
    writing files..
    writing plist..
    populating database..
    finished populating sqlite database..

  processing: pipes-4.1.2
    writing files..
    writing plist..
    populating database..
    finished populating sqlite database..

  warning: failed to process: parsec-3.1.5
  warning: path errors in pkg conf file:
   /home/jpf/local/cabal-sandboxes/dash-haskell/x86_64-linux-ghc-7.8.3-packages.conf.d/parsec-3.1.5-abf7e89cafe4e74712f678cea843c1c8.conf
  with problem(s):
   missing: haddock interface file
   missing: html doc dir

  processing: sqlite-simple-0.4.8.0
    writing files..
    writing plist..
    populating database..
    finished populating sqlite database..

  $

Notice, the failure of parsec-3.1.5 is illustrated here to show that in this case, dash-haskell depends on haddock documentation being built for the requested package. A possible resolution in this case, if using a sandbox, is:

$ cabal install --reinstall parsec-3.1.5 --enable-documentation
$ dash-haskell parsec-3.1.5 -o docsets

dash-haskell tries to be as self-documenting as possible. Please see:

$ dash-haskell help [option|topic]

Installation

$ cabal install dash-haskell

or

 $ git clone http://www.github.com/jfeltz/dash-haskell
 $ cd dash-haskell
 $ cabal install 

Package Resolution

When dependency sourcing from a cabal file, dash-haskell does not (yet) select versioned packages from the build-dependency version bounds, only the package names. As a general rule, try to be version specific when providing package arguments, unless you're judicious about which packages are stored in your cabal sandbox or ghc package db. There is a lot of hidden behavior that goes into how dash-haskell resolves packages, for example, consider the hypothetical package arguments:

$ dash-haskell either parsec-1.2 parsec

This chooses by default:

IDE Configuration

To use the generated docsets , you will need a plugin for your particular IDE which can access them.

(defun activate-package-docsets (root) (progn (setq helm-dash-docsets-path root) (setq helm-dash-common-docsets (helm-dash-installed-docsets))

 (message 
  (format "activated %d docsets from: %s" 
    (length helm-dash-common-docsets) root))

))


```lisp
(activate-package-docsets "/path/to/project/docsets/")

Features slated for V2

Contributors

Hirotomo Moriwaki philopon.dependence@gmail.com

The major instigator of this project was Hirotomo Moriwaki's haddocset, with much of the early implementation of dash-haskell influenced by that code-base.

Author & Maintainer

John P. Feltz jfeltz@gmail.com