To build a local copy of the nbodykit docs, install the programs in environment.yml and run 'make html'. If you use the conda package manager these commands suffice:

git clone [email protected]:bccp/nbodykit.git
cd nbodykit/docs
conda env create --name nbodykitdocs -f environment.yml
source activate nbodykitdocs
make html
open build/html/index.html

Notebooks in source/cookbook are downloaded at build time from the bccp/nbodykit-cookbook repository. Developers should modify and add new recipes to this repository to update the cookbook in the docs.

Notebooks in this directory tree should NOT be modified. All .ipynb files in source/cookbook are ignored by git.

To execute all notebooks in the documentation that do not live in source/cookbook, use:

python helper_scripts/run_notebooks.py

or equivalently, you can use make ipynb.

We use the nbsphinx extension to include .ipynb files in the docs. A few useful things to know:

1. Hidden Cells: You can include hidden cells in the notebook, which will not show up in the HTML output, by editing the cell metadata. Use View -> Cell Toolbar -> Edit Metadata, and then go to the cell you want, click edit metadata, and insert into the metadata dictionary the key/value pair: "nbsphinx" : "hidden".
2. ReST Cells: You can include raw restructured text cells in the notebook, which will be converted properly. You must set the cell type to raw ReST. This can be done using: View -> Cell Toolbar -> Raw Cell Format, and then going to the cell you want, and setting the type to ReST.
3. Linking to notebook files: From other RST files, you can link to the notebooks via the ref directive. The important thing to remember is that you must use the full notebook file path, as if the top level directory is source. So you can link to a notebook in the cookbook directory, using the path "cookbook/lognormal-mocks.ipynb".