# Building docs #
To build docs, run `make` in this directory. `make help` lists all targets.

## Requirements ##
Sphinx and Latex is needed to build doc.

**Sphinx:**
```sh
pip install sphinx
```

**Latex Ubuntu:**
```sh
sudo apt-get install -qq texlive texlive-latex-extra dvipng
```

**Latex Mac:**

Install the full [MacTex](http://www.tug.org/mactex/) installation or install the smaller [BasicTex](http://www.tug.org/mactex/morepackages.html) and add *ucs* and *dvipng* packages:
```sh
sudo tlmgr install ucs dvipng
```


## Fixing Warnings ##

- "citation not found: R###"
  $ cd doc/build; grep -rin R### .
  There is probably an underscore after a reference
  in the first line of a docstring (e.g. [1]_)

- "Duplicate citation R###, other instance in...""
  There is probably a [2] without a [1] in one of
  the docstrings

- Make sure to use pre-sphinxification paths to images
  (not the _images directory)


## Auto-generating dev docs ##

This set of instructions was used to create scikit-image/tools/deploy-docs.sh

- Go to Github account settings -> personal access tokens
- Create a new token with access rights `public_repo` and `user:email only`
- Install the travis command line tool: `gem install travis`.  On OSX, you can get gem via `brew install ruby`.
- Take then token generated by Github and run `travis encrypt GH_TOKEN=<token>` from inside a scikit-image repo
- Paste the output into the secure: field of `.travis.yml`.
- The decrypted GH_TOKEN env var will be available for travis scripts

https://help.github.com/articles/creating-an-access-token-for-command-line-use/
http://docs.travis-ci.com/user/encryption-keys/