dash-haskell (empty) → 1.0.0.0

raw patch · 5 files changed

+558/−0 lines, 5 filesdep +Cabaldep +basedep +bytestringsetup-changed

Dependencies added: Cabal, base, bytestring, containers, direct-sqlite, directory, either, ghc, haddock-api, mtl, optparse-applicative, parsec, pipes, process, sqlite-simple, system-fileio, system-filepath, tagsoup, text, transformers

Files

• LICENSE +165/−0
• README.md +224/−0
• Setup.hs +2/−0
• dash-haskell.cabal +128/−0
• src/Main.hs +39/−0

@@ -0,0 +1,165 @@+                  GNU LESSER GENERAL PUBLIC LICENSE+                       Version 3, 29 June 2007++ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>+ Everyone is permitted to copy and distribute verbatim copies+ of this license document, but changing it is not allowed.+++  This version of the GNU Lesser General Public License incorporates+the terms and conditions of version 3 of the GNU General Public+License, supplemented by the additional permissions listed below.++  0. Additional Definitions.++  As used herein, "this License" refers to version 3 of the GNU Lesser+General Public License, and the "GNU GPL" refers to version 3 of the GNU+General Public License.++  "The Library" refers to a covered work governed by this License,+other than an Application or a Combined Work as defined below.++  An "Application" is any work that makes use of an interface provided+by the Library, but which is not otherwise based on the Library.+Defining a subclass of a class defined by the Library is deemed a mode+of using an interface provided by the Library.++  A "Combined Work" is a work produced by combining or linking an+Application with the Library.  The particular version of the Library+with which the Combined Work was made is also called the "Linked+Version".++  The "Minimal Corresponding Source" for a Combined Work means the+Corresponding Source for the Combined Work, excluding any source code+for portions of the Combined Work that, considered in isolation, are+based on the Application, and not on the Linked Version.++  The "Corresponding Application Code" for a Combined Work means the+object code and/or source code for the Application, including any data+and utility programs needed for reproducing the Combined Work from the+Application, but excluding the System Libraries of the Combined Work.++  1. Exception to Section 3 of the GNU GPL.++  You may convey a covered work under sections 3 and 4 of this License+without being bound by section 3 of the GNU GPL.++  2. Conveying Modified Versions.++  If you modify a copy of the Library, and, in your modifications, a+facility refers to a function or data to be supplied by an Application+that uses the facility (other than as an argument passed when the+facility is invoked), then you may convey a copy of the modified+version:++   a) under this License, provided that you make a good faith effort to+   ensure that, in the event an Application does not supply the+   function or data, the facility still operates, and performs+   whatever part of its purpose remains meaningful, or++   b) under the GNU GPL, with none of the additional permissions of+   this License applicable to that copy.++  3. Object Code Incorporating Material from Library Header Files.++  The object code form of an Application may incorporate material from+a header file that is part of the Library.  You may convey such object+code under terms of your choice, provided that, if the incorporated+material is not limited to numerical parameters, data structure+layouts and accessors, or small macros, inline functions and templates+(ten or fewer lines in length), you do both of the following:++   a) Give prominent notice with each copy of the object code that the+   Library is used in it and that the Library and its use are+   covered by this License.++   b) Accompany the object code with a copy of the GNU GPL and this license+   document.++  4. Combined Works.++  You may convey a Combined Work under terms of your choice that,+taken together, effectively do not restrict modification of the+portions of the Library contained in the Combined Work and reverse+engineering for debugging such modifications, if you also do each of+the following:++   a) Give prominent notice with each copy of the Combined Work that+   the Library is used in it and that the Library and its use are+   covered by this License.++   b) Accompany the Combined Work with a copy of the GNU GPL and this license+   document.++   c) For a Combined Work that displays copyright notices during+   execution, include the copyright notice for the Library among+   these notices, as well as a reference directing the user to the+   copies of the GNU GPL and this license document.++   d) Do one of the following:++       0) Convey the Minimal Corresponding Source under the terms of this+       License, and the Corresponding Application Code in a form+       suitable for, and under terms that permit, the user to+       recombine or relink the Application with a modified version of+       the Linked Version to produce a modified Combined Work, in the+       manner specified by section 6 of the GNU GPL for conveying+       Corresponding Source.++       1) Use a suitable shared library mechanism for linking with the+       Library.  A suitable mechanism is one that (a) uses at run time+       a copy of the Library already present on the user's computer+       system, and (b) will operate properly with a modified version+       of the Library that is interface-compatible with the Linked+       Version.++   e) Provide Installation Information, but only if you would otherwise+   be required to provide such information under section 6 of the+   GNU GPL, and only to the extent that such information is+   necessary to install and execute a modified version of the+   Combined Work produced by recombining or relinking the+   Application with a modified version of the Linked Version. (If+   you use option 4d0, the Installation Information must accompany+   the Minimal Corresponding Source and Corresponding Application+   Code. If you use option 4d1, you must provide the Installation+   Information in the manner specified by section 6 of the GNU GPL+   for conveying Corresponding Source.)++  5. Combined Libraries.++  You may place library facilities that are a work based on the+Library side by side in a single library together with other library+facilities that are not Applications and are not covered by this+License, and convey such a combined library under terms of your+choice, if you do both of the following:++   a) Accompany the combined library with a copy of the same work based+   on the Library, uncombined with any other library facilities,+   conveyed under the terms of this License.++   b) Give prominent notice with the combined library that part of it+   is a work based on the Library, and explaining where to find the+   accompanying uncombined form of the same work.++  6. Revised Versions of the GNU Lesser General Public License.++  The Free Software Foundation may publish revised and/or new versions+of the GNU Lesser General Public License from time to time. Such new+versions will be similar in spirit to the present version, but may+differ in detail to address new problems or concerns.++  Each version is given a distinguishing version number. If the+Library as you received it specifies that a certain numbered version+of the GNU Lesser General Public License "or any later version"+applies to it, you have the option of following the terms and+conditions either of that published version or of any later version+published by the Free Software Foundation. If the Library as you+received it does not specify a version number of the GNU Lesser+General Public License, you may choose any version of the GNU Lesser+General Public License ever published by the Free Software Foundation.++  If the Library as you received it specifies that a proxy can decide+whether future versions of the GNU Lesser General Public License shall+apply, that proxy's public statement of acceptance of any version is+permanent authorization for you to choose that version for the+Library.

@@ -0,0 +1,224 @@+dash-haskell+============+**local and approximate package doc access for your Haskell project dependencies**++  **direct to browser lookup:**+  ![look-up](/img/lookup.png?raw=true)+ ++  **keyword, module, and package searching:**+  ![listing](/img/listing.png?raw=true)++The purpose of the dash-haskell is to facilitate Haskell documentation in IDE(s), with the following qualities:+  +  * **Local**++    Documentation is stored in [dash](http://kapeli.com/dash) docsets on the filesystem,+    avoiding the need to query **often inaccurate, version lagged** information from a remote resource such as *hackage*,+    *hoogle*, or *hayoo*.+    +  * **Resolved from Project Dependencies**++    With dash-haskell, one can build dash docsets from:+     * packages listed as dependencies of a *.cabal file+     * packages in a cabal sandbox+     * an arbitrary package db++  * **Scope Narrowed**+    +    IDE plugins such as [helm-dash](https://github.com/areina/helm-dash)+    allow for only specific docsets to be active. This means that+    when searching for an identifier, e.g. *fromJust*, only the+    packages you've built in your configuration are searched. Searches+    can then be further narrowed by module etc.++  * **Prolifically Standardized** ++    [dash docsets](http://kapeli.com/dash) are an open, easily assimilated standard, and+    are used across many IDE(s).++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:++* ```either``` and ```parsec-1.2``` as the parameter packages. +  If for example ```parsec``` were sourced from a cabal file, with ```-c```, +  ```parsec-1.2``` would still be chosen instead. +* cabal as a package db provider:+  implicitly calling ```cabal sandbox hc-pkg list```.+  By convention the first db that provides the unversioned package is chosen.+* ```either-4.1.0``` and ```parsec-1.2``` are then selected from the package db,+where their config files are parsed for the documentation sources to be converted. +++IDE Configuration+=================+To use the generated docsets , you will need a plugin for your particular IDE which can access+them.++* **Emacs**++  **dash-haskell** is tested with the following for emacs:++  * [helm](https://github.com/emacs-helm/helm) , a fuzzy finder plugin for emacs+  * [helm-dash](https://github.com/areina/helm-dash) , the essential extension to helm in order to lookup dash docsets++  For limiting helm-dash to project specific docsets, the following also helps. ++  ```lisp+(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/")+```++* For **Vim**, see the following known docset plugins:++    * The zealdocs [vim plugin](http://www.zealdocs.org)+    * The Dash.app [vim plugin](https://github.com/rizzatti/dash.vim)++Features slated for V2+======================+* handle **docset pre-builts**++    set pre-built criteria, pre-built skipping, and provide a ```--rebuild``` to force rebuild of a docset++* **summaries**++    provide summary information to help users better understand which+    packages failed and succeeded++* **version biasing** ++    provide option to bias package version to highest when it is otherwise ambiguous++* ```conf``` argument support ++    build docset directly from a package db .conf ++* ```doc``` argument ++    build docsets directly from a package doc directory +    (containing the requisite ```*.haddock``` interface and html files)++Contributors+============+Hirotomo Moriwaki <philopon.dependence@gmail.com>++The major instigator of this project was Hirotomo Moriwaki's [haddocset](https://github.com/philopon/haddocset), with much of the early implementation of *dash-haskell* influenced by that code-base.++Author & Maintainer+===================+John P. Feltz <jfeltz@gmail.com>

@@ -0,0 +1,2 @@+import Distribution.Simple+main = defaultMain

@@ -0,0 +1,128 @@+name:                dash-haskell+version:             1.0.0.0+synopsis:            Command line tool to generate Dash docsets (IDE docs) from package haddock+homepage:            http://www.github.com/jfeltz/dash-haskell+Bug-reports:         https://github.com/jfeltz/dash-haskell/issues+license:             LGPL-3+license-file:        LICENSE+author:              John P. Feltz+maintainer:          jfeltz@gmail.com+copyright:           (c) 2014 John P. Feltz +category:            Documentation+build-type:          Simple+cabal-version:       >= 1.18+extra-source-files:  README.md ++description: +  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+  .+++executable dash-haskell+  main-is:             Main.hs+  build-depends:       Cabal                >= 1.18+                     , base                 >= 4.7 && <4.8+                     , bytestring           >= 0.10.0.1+                     , containers           >= 0.5.5.1+                     , direct-sqlite >= 2.3.13+                     , directory            >= 1.2.1.0+                     , either               >= 4.3+                     , ghc                  >= 7.8.3+                     , mtl                  >= 2.1.3.1+                     , optparse-applicative >= 0.10.0+                     , 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+                     , parsec               >= 3.1.5+                     , haddock-api          >= 2.15.0+  ghc-options:         -Wall -rtsopts+  hs-source-dirs:      src+  default-language:    Haskell2010

@@ -0,0 +1,39 @@+import qualified Filesystem.Path.CurrentOS as P+import           Control.Monad.M+import           Pipes+import           Pipes.FileSystem+import           Pipes.Conf+import           Pipes.Db+import           Options.Applicative+import           Options.Documentation+import           Options++import qualified Data.List as L+import           System.Environment++main :: IO ()+main = do +  -- Check for help mode arg first. There doesn't seem to be a good way to do this+  -- otherwise with opt-parse applicative.+  args <- getArgs+  case L.partition (== "help") args of +    ([], args') -> do+      options <- handleParseResult $ execParserPure (prefs idm) parserInfo args'+      +      -- Run the package processing pipeline. Packages that can't be completed due+      -- to either conversion error or user error, should, if necessary, leave a safe partially+      -- completed state on the FS that can be handled by dependant tools, e.g. Emacs helm-dash.++      runM (newEnv (not . quiet $ options)) . runEffect $+       cons_writeFiles (P.decodeString $ outputDir options) -- writes converted html, haddock, and sql db+       <-< pipe_Conf              -- yields vetted package configurations+       <-< pipe_ConfFp (dbprovider options)  -- yields GHC package config files+       <-< prod_Packages options+    (_, rest) -> toHelp docs rest+  +  where +   parserInfo :: ParserInfo Options+   parserInfo = info (helper <*> parser)  $+     header "dash-haskell v1.0.0.0, a dash docset construction tool for Haskell packages"+     <> progDesc "additional help is available with \"dash-haskell help <topic|option>\""+     <> footer "http://www.github.com/jfeltz/dash-haskell (C) John P. Feltz 2014"