https://github.com/diagrams/diagrams-doc

Documentation for the diagrams project
https://github.com/diagrams/diagrams-doc

Last synced: 5 days ago
JSON representation

Documentation for the diagrams project

• Host: GitHub
• URL: https://github.com/diagrams/diagrams-doc
• Owner: diagrams
• Created: 2012-07-24T23:25:01.000Z (over 12 years ago)
• Default Branch: master
• Last Pushed: 2023-11-01T10:08:51.000Z (about 1 year ago)
• Last Synced: 2024-08-01T12:25:40.525Z (3 months ago)
• Language: HTML
• Size: 71 MB
• Stars: 19
• Watchers: 13
• Forks: 27
• Open Issues: 19
• Metadata Files:
  • Readme: README.markdown

Awesome Lists containing this project

• awesome-starred - diagrams/diagrams-doc - Documentation for the diagrams project (others)

README

        
[![Build Status](https://secure.travis-ci.org/diagrams/diagrams-doc.png)](http://travis-ci.org/diagrams/diagrams-doc)

This repository holds all documentation for the

[diagrams framework](http://projects.haskell.org/diagrams), including

* the [website](http://projects.haskell.org/diagrams) source

* [tutorials](http://projects.haskell.org/diagrams/documentation.html)

* [user manual](http://projects.haskell.org/diagrams/doc/manual.html)

* IRC logs

* blog posts

* related papers and talks

* release checklists

and more.

## Building

### Step 1: Get dependencies

To build the website (which includes the gallery, user manual, and

tutorials), you will need:

* [stack](http://github.com/commercialhaskell/stack)

* the python [docutils suite](http://docutils.sourceforge.net/) (in

  particular `rst2xml.py` should be on your PATH).

For example, on Ubuntu, the docutils suite can be installed using

```bash

sudo apt-get install python-docutils

```

(or possibly `python3-docutils`, depending on what version of Ubuntu

you have).

### Step 2: Generate the `stack.yaml` file

Run the command

```bash

./generate-stack-yaml.hs

```

This will generate a `stack.yaml` file that contains the necessary

dependencies to build this project. This includes each Diagrams Github repo,

so that you can build the documentation against the latest versions of each

project. If new commits get pushed to the Diagrams repos, you may need to

re-run `./generate-stack-yaml.hs`.

### Step 3: Run the builder

Once you have all the dependencies, simply do

```bash

stack build

stack exec diagrams-doc -- +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 website. 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 `stack exec diagrams-doc -- preview` running, and then start

another process calling `stack exec diagrams-doc -- build` repeatedly in a

loop.  The website will now automatically be rebuilt any time any

source files change.