diagrams / diagrams-haddock Goto Github PK

Preprocessor for including inline diagrams in Haddock documentation

License: Other

Haskell 100.00%

diagrams-haddock's Introduction

diagrams is a full-featured framework and domain-specific language (embedded in Haskell) for creating declarative vector graphics and animations.

This package is just a convenient wrapper around the diagrams-core, diagrams-lib, diagrams-svg, and diagrams-contrib packages, so they can be installed with a single cabal install --lib diagrams command.

The package also comes with flags to enable six different backends. The native SVG backend is enabled by the -fsvg flag and is enabled by default. If you don't want it, you must explicitly disable it with -f-svg.

The native postscript backend is disabled by default but can be enabled by the -fps flag.

The cairo backend is disabled by default but can be selected with the -fcairo flag. In addition, the GTK backend is based on the cairo backend (but split into a separate package to make installing the cairo backend easier). It can be selected with the fgtk flag.

The native rasterific backend which is disabled by default but can be selected with the -frasterific flag.

The native canvas backend which is disabled by default but can be selected with the -fcanvas flag.

Installation

cabal update && cabal install --lib diagrams

or, to get the postscript backend in addition to the SVG backend:

cabal update && cabal install --lib -fps diagrams

or, to get the cairo backend in addition to the SVG backend:

cabal update && cabal install gtk2hs-buildtools && cabal install --lib -fcairo diagrams

Reporting bugs

Issue trackers for all diagrams-related repositories are hosted under the diagrams organization on github. If you know the specific package containing the bug, report it in the issue tracker specific to that package (for example, diagrams-lib). Otherwise, just report the issue in the issue tracker for the general diagrams repository.

Probably the right fix is to do some actual dependency analysis, and only include code blocks transitively referenced by the code block including the diagram being built. To really do this properly would require doing name resolution, but not doing name resolution and simply taking every identifier to be a global reference will always give a conservative approximation (i.e. superset) of the precisely correct group of code blocks.

Note, doing this also means we can do away with the strange restriction that supporting code must be included in the same code block with some referenced diagram definition.

Deprecate `diagrams-haddock`?

diagrams-haddock is hard to maintain, and this post makes me wonder if it's obsolete: instead of using a finicky custom tool like diagrams-haddock, one should just write doctests that happen to use diagrams to render images.

update tasty version bound

See commercialhaskell/stackage#285 .

Support PNG and GIF

I seem to have created an 11M SVG. It would be more economical to use a PNG. I'd also like to be able to embed animations (GIF).

Compilation failure due to missing Show instance

Running:

cabal install diagrams-haddock --constraint 'diagrams-builder==0.4.2'

Results in:

src/Diagrams/Haddock.hs:454:9:
    No instance for (Show (Options SVG Diagrams.TwoD.Types.R2))
      arising from a use of `buildDiagram'
    Possible fix:
      add an instance declaration for
      (Show (Options SVG Diagrams.TwoD.Types.R2))
    In a stmt of a 'do' block:
      buildDiagram
        SVG
        zeroV
        (SVGOptions (mkSizeSpec w h) Nothing)
        (map (view codeBlockCode) neededCode)
        (url ^. diagramName)
        []
        ["Diagrams.Backend.SVG"]
        (hashedRegenerate (\ _ opts -> opts) cacheDir)
    In the second argument of `($)', namely
      `do { createDirectoryIfMissing True cacheDir;
            when (not dataURIs) $ createDirectoryIfMissing True outputDir;
            logStr $ "[ ] " ++ (url ^. diagramName);
            IO.hFlush IO.stdout;
            .... }'
    In a stmt of a 'do' block:
      res <- liftIO
             $ do { createDirectoryIfMissing True cacheDir;
                    when (not dataURIs) $ createDirectoryIfMissing True outputDir;
                    logStr $ "[ ] " ++ (url ^. diagramName);
                    IO.hFlush IO.stdout;
                    .... }
Failed to install diagrams-haddock-0.2.1.6
cabal: Error: some packages failed to install:
diagrams-haddock-0.2.1.6 failed during the building phase. The exception was:
ExitFailure 1

Does not build with ghc 8

cabal: Could not resolve dependencies:
trying: diagrams-haddock-0.3.0.10 (user goal)
next goal: base (dependency of diagrams-haddock-0.3.0.10)
rejecting: base-4.9.0.0/installed-4.9... (conflict: diagrams-haddock =>
base>=4.4 && <4.9)
rejecting: base-4.9.0.0, base-4.8.2.0, base-4.8.1.0, base-4.8.0.0,
base-4.7.0.2, base-4.7.0.1, base-4.7.0.0, base-4.6.0.1, base-4.6.0.0,
base-4.5.1.0, base-4.5.0.0, base-4.4.1.0, base-4.4.0.0, base-4.3.1.0,
base-4.3.0.0, base-4.2.0.2, base-4.2.0.1, base-4.2.0.0, base-4.1.0.0,
base-4.0.0.0, base-3.0.3.2, base-3.0.3.1 (constraint from non-upgradeable
package requires installed instance)
Dependency tree exhaustively searched.

Failure to find setup-config

~/Dropbox/Private/diagrams-contrib $ ls -ltr dist/dist-sandbox-79e8b561/setup-config 
-rw-------  1 dom  staff  449364 Apr 11 16:31 dist/dist-sandbox-79e8b561/setup-config

~/Dropbox/Private/diagrams-contrib $ diagrams-haddock -d=dist/dist-sandbox-79e8b561
No setup-config found in ./dist/dist-sandbox-79e8b561, please run 'cabal configure' first.

Cabal mis-match puzzle

modified   diagrams-haddock.cabal
@@ -68,7 +68,7 @@ Executable diagrams-haddock
                        filepath,
                        diagrams-haddock,
                        cmdargs >= 0.8 && < 0.11,
-                       Cabal >= 1.14 && < 1.25,
+                       Cabal == 1.25.0.0,
                        cpphs >= 1.15
   hs-source-dirs:      tools
   default-language:    Haskell2010
@@ -78,7 +78,7 @@ Test-suite diagrams-haddock-tests
   main-is:             Tests.hs
   build-depends:       base,
                        containers >= 0.4 && < 0.6,
-                       QuickCheck >= 2.4 && < 2.9,
+                       QuickCheck >= 2.4 && < 2.10,
                        tasty >= 0.8 && < 0.12,
                        tasty-quickcheck >= 0.8 && < 0.9,
                        parsec >= 3,

And also

~/Dropbox/Private/Libraries/Kalman $ ../diagrams-haddock/dist/build/diagrams-haddock/diagrams-haddock
diagrams-haddock: No appropriate setup-config found in ./dist
Either it does not exist or it is in the wrong format.
* You may need to run 'cabal configure' first.
* Make sure that the version of Cabal used to compile
  diagrams-haddock (1.25.0.0) matches the version used
  by the cabal tool.
* Use the -d option if you want diagrams-haddock to look in
  a different dist directory.

But

~/Dropbox/Private/Libraries/Kalman $ cabal --version
cabal-install version 1.25.0.0
compiled using version 1.25.0.0 of the Cabal library

Also if I try to create a diagram from one source file

~/Dropbox/Private/Libraries/Kalman $ ../diagrams-haddock/dist/build/diagrams-haddock/diagrams-haddock src/Numeric/Kalman.hs 
~/Dropbox/Private/Libraries/Kalman $

AFAICS no output is produced.

Here's the haddock that I hoped would produce a diagram

-- <<diagrams/src_Numeric_Kalman_diag.svg#diag=diag&height=600&width=500>>
--
-- > import Graphics.Rendering.Chart
-- > import Data.Colour
-- > import Data.Colour.Names
-- > import Data.Default.Class
-- > import Graphics.Rendering.Chart.Backend.Cairo
-- > import Control.Lens
-- >
-- > setLinesBlue :: PlotLines a b -> PlotLines a b
-- > setLinesBlue = plot_lines_style  . line_color .~ opaque blue
-- >
-- > chart = toRenderable layout
-- >   where
-- >     am :: Double -> Double
-- >     am x = (sin (x*3.14159/45) + 1) / 2 * (sin (x*3.14159/5))
-- >
-- >     sinusoid1 = plot_lines_values .~ [[ (x,(am x)) | x <- [0,(0.5)..400]]]
-- >               $ plot_lines_style  . line_color .~ opaque blue
-- >               $ plot_lines_title .~ "am"
-- >               $ def
-- >
-- >     sinusoid2 = plot_points_style .~ filledCircles 2 (opaque red)
-- >               $ plot_points_values .~ [ (x,(am x)) | x <- [0,7..400]]
-- >               $ plot_points_title .~ "am points"
-- >               $ def
-- >
-- >     layout = layout_title .~ "Amplitude Modulation"
-- >            $ layout_plots .~ [toPlot sinusoid1,
-- >                               toPlot sinusoid2]
-- >            $ def
-- >
-- > diag = do
-- >   denv <- defaultEnv vectorAlignmentFns 600 500
-- >   return $ fst $ runBackend denv (render chart (600, 500))
--
module Numeric.Kalman
...

Better error reporting for code blocks that fail to parse

Right now code blocks that don't parse are silently ignored. Some sort of error or warning should be printed.

Find proper distdir if an hsenv environment is active

Currently we always default to using dist, but we ought to check to see if an hsenv environment is active, and use the proper distdir.

Add data URI output as optional behavior

We should add an optional flag which causes diagrams-haddock to output images to embedded data URIs instead of to external files. This bloats the source files considerably but has the benefit that no fiddling with custom cabal setups or extra-source-file fields is necessary. I don't personally think it makes a good default, but we can just give users the option and let them decide for themselves.

Restrictive upper bound in test suite

While the library allows haskell-src-exts 1.15, the test suite says:

haskell-src-exts >= 1.14 && < 1.15,

Can this be relaxed?

diagrams with the same name clobber each other

If two diagrams in different files within the same Cabal project happen to have the same name, one of them overwrites the other one. I don't know if this counts as a "bug" but it certainly is an "infelicity" at least. It would be nice if we could work out some way of disambiguating/preventing clobbering.

Diagram url inside skipped #ifdef.

If you have a diagram url inside a skipped #ifdef it will correctly ignore the code in comments for that section, but incorrectly find that url. This issues a warning, but is unlikely to cause harm.

diagrams-haddock does not properly roundtrip non-ASCII UTF-8

Here's a minimal test case:

archimedes :: src/diagrams/haddock » cat > TestUTF8.hs
-- á
-- <<foo#diagram=foo&width=100>>
-- > foo = circle 1
archimedes :: src/diagrams/haddock » head -n 1 TestUTF8.hs | hexdump -C
00000000  2d 2d 20 c3 a1 0a                                 |-- ...|
00000006
archimedes :: src/diagrams/haddock » diagrams-haddock TestUTF8.hs
archimedes :: src/diagrams/haddock » head -n 1 TestUTF8.hs | hexdump -C
00000000  2d 2d 20 e1 0a                                    |-- ..|
00000005

Note how the bytes c3a1 (the UTF-8 encoding of á) turn into e1 (the ISO-8859-1 encoding of á). And it completely barfs on something outside of ISO-8859-1. E.g., let's try a snowman:

archimedes :: src/diagrams/haddock » cat > TestUTF8.hs
-- ☃
-- <<foo#diagram=foo&width=100>>
-- > foo = circle 1
archimedes :: src/diagrams/haddock » head -n 1 TestUTF8.hs | hexdump -C
00000000  2d 2d 20 e2 98 83 0a                              |-- ....|
00000007
archimedes :: src/diagrams/haddock » diagrams-haddock TestUTF8.hs
archimedes :: src/diagrams/haddock » head -n 1 TestUTF8.hs | hexdump -C
00000000  2d 2d 20 03 0a                                    |-- ..|
00000005

0.3.0.8: src/Diagrams/Haddock.hs:458:55: Couldn't match expected type

diagrams-haddock-0.3.0.8 failed to build in Stackage Nightly:

src/Diagrams/Haddock.hs:458:55:
    Couldn't match expected type ‘[t0]
                                  -> Bool -> Options SVG V2 Double’
                with actual type ‘Options SVG V2 Double’
    The function ‘SVGOptions’ is applied to five arguments,
    but its type ‘Diagrams.Size.SizeSpec V2 Double
                  -> Maybe diagrams-svg-1.3.1.7:Graphics.Rendering.SVG.SvgM
                  -> Data.Text.Internal.Text
                  -> Options SVG V2 Double’
    has only three
    In the third argument of ‘DB.mkBuildOpts’, namely
      ‘(SVGOptions (mkSizeSpec2D w h) Nothing "" [] False)’
    In the first argument of ‘(&)’, namely
      ‘DB.mkBuildOpts
         SVG zero (SVGOptions (mkSizeSpec2D w h) Nothing "" [] False)’

Support for cabal sandboxes

diagrams-haddock ought to support cabal sandboxes out of the box. Probably the processCabalPackage function

https://github.com/diagrams/diagrams-haddock/blob/master/tools/diagrams-haddock.hs#L111

needs to be updated to look for an existing cabal sandbox and choose the dist dir appropriately.

Processing kills file when an HSE exception happens.

When parsing causes an exception due to a bug in HSE we die while writing the file.

ghci> :! cat test.hs
{-# LANGUAGE TypeFamilies #-}
-- <<blah#diagram=ha>>
-- > ha = circle 1
instance a ~ b => Blah a
ghci> import Diagrams.Haddock
ghci> processHaddockDiagrams "./" "./" "test.hs"
*** Exception: src/Language/Haskell/Exts/Annotated/ExactPrint.hs:(952,9)-(956,22): Non-exhaustive patterns in case

ghci> :! cat test.hs
ghci>

A few errors when run against diagrams-lib

I wrote a little script to run diagrams-haddock against diagrams-lib and it encountered a couple of problems http://hpaste.org/83072.

The strangest one is removing of a space in src/Diagrams/Coordinates.hs:

-data a :& b = a :& b
+data a :& b = a :&b

process the .cabal file for Cabal projects in addition to source files

Authors may wish to include diagrams in the description field of their Cabal package, and there's no technical reason not to allow it.

Don't require `dummy#` part of diagram URL

This way users can just write <<diagram=foo&width=200>> to create a diagram.

Parallelism!

diagrams-haddock has some embarrassing parallelism going on. We should add a -j flag that turns on multithreading.

Add logging output

It would be nice to have some indication of what diagrams-haddock is doing, i.e. output messages of the form "Processing Foo/Bar.hs..." or something like that by default. And I suppose there should also be a command-line argument like -q to suppress them.

diagrams / diagrams-haddock Goto Github PK

diagrams-haddock's Introduction

Installation

Reporting bugs

Further reading

diagrams-haddock's People

Contributors

Stargazers

Watchers

Forkers

diagrams-haddock's Issues

Recommend Projects

Recommend Topics

Recommend Org