# Documenting traitlets


[Documentation for `traitlets`](https://traitlets.readthedocs.io/en/latest/)
is hosted on ReadTheDocs.


## Build documentation locally

#### Change directory to documentation root:

    cd docs

#### Create environment

* [**conda**] Create conda env (and install relevant dependencies):

        conda env create -f environment.yml

* [**pip**] Create virtual environment (and install relevant dependencies):

        virtualenv traitlets_docs -p python3
        pip install -r requirements.txt

#### Activate the newly built environment `traitlets_docs`

* [**conda**] Activate conda env:

        source activate traitlets_docs

* [**pip**] The virtualenv should have been automatically activated. If
     not:

        source activate

#### Build documentation using:

* Makefile for Linux and OS X:

        make html

* make.bat for Windows:

        make.bat html


#### Display the documentation locally

* Navigate to `build/html/index.html` in your browser.

* Or alternatively you may run a local server to display
  the docs. In Python 3:

        python -m http.server 8000

  In your browser, go to `http://localhost:8000`.


## Developing Documentation

[Jupyter documentation guide](https://jupyter.readthedocs.io/en/latest/contrib_docs/index.html)


## Helpful files and directories

* `source/conf.py` - Sphinx build configuration file
* `source` directory - source for documentation
* `source/index.rst` - Main landing page of the Sphinx documentation
* `requirements.txt` - list of packages to install when using pip
* `environment.yml` - list of packages to install when using conda