pnutus / diagrams-doc

Documentation for the diagrams project

This repository holds all documentation for the diagrams framework, including

• the website source
• tutorials
• user manual
• IRC logs
• blog posts
• related papers and talks
• release checklists

and more.

Building

To build the website (which includes the gallery, user manual, and tutorials), you will need:

• GHC 7.8
• the diagrams framework itself (including the contrib package, SVGFonts package, palette package, and diagrams-builder package).
• Either the rasterific backend (recommended) or the SVG backend. See below for more information re: using the SVG backend.
• the python docutils suite (in particular rst2xml.py should be on your PATH).
• the Haskell docutils package (note it is not on Hackage; just clone the master branch from github and cabal install it).
• the latest version of shake.
• hakyll-4.x.
• safe.

Once you have all the dependencies, simply do

ghc --make Shake -threaded
./Shake +RTS -N4 -RTS preview

which will build the user manual and website, and run a web server on port 8000 serving a preview of the webiste. In place of -N4 you should use -NX where X is the number of cores you have. By default, the build system will use all but one of your available cores; if you wish to set the number to something else, set the DIA_DOC_THREADS environment variable.

Point your browser at localhost:8000 to view it. It works well to leave this invocation of Shake preview running, and then start another process calling Shake +RTS -NX -RTS build repeatedly in a loop. The website will now automatically be rebuilt any time any source files change.

For example, on a four-core Ubuntu machine, assuming you already have the Haskell Platform installed and want to use the rasterific backend, you could first clone the relevant diagrams repositories from github:

• diagrams-core
• diagrams-solve
• active
• diagrams-lib
• diagrams-cairo
• diagrams-contrib
• diagrams-builder
• diagrams-rasterific
• SVGFonts
• palette
• docutils

Then run the following commands:

sudo apt-get install python-docutils
cabal sandbox init
cabal install diagrams-core/ diagrams-solve/ diagrams-lib/ diagrams-rasterific/ diagrams-contrib/ diagrams-builder/ SVGFonts/ palette/ docutils/ shake hakyll safe
cabal exec bash
cd diagrams-doc
ghc --make Shake -threaded
./Shake +RTS -N4 -RTS preview

Building with diagrams-svg

The build system will first check for an installed diagrams-rasterific package. If none is found, it will fall back to using the diagrams-svg package. As of right now, there are no known issues with using diagrams-svg for building the website (other than the fact that some of the output .svg files are large).