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 andcabal 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
diagrams-svg
Building with 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).