Usage

Note 1: this guide currently omits any mention of notebook testing; that will come in a future version.

Note 2: this is a pre-release version of nbsite, so you may subsequently have to change your config on upgrading to a newer version of nbsite. You may also encounter problems and/or limitations - please file issues or ask questions on GitHub.

Prerequisites

  1. You want a 'static', fairly self contained site (i.e. just an ordinary web server is required - you can build and serve locally, or copy the build directory to a remote server).

  2. You have one or more sets of notebooks (e.g. notebooks/, or examples/getting_started + examples/user_guide + examples/gallery). Note: current expectation is for there to be no title in the notebook itself; instead, the title will be taken from filename. E.g. 1_The_Filename.ipynb will result in a title of 1 The Filename. Additionally, notebooks should use level 2 headings as their highest heading level (level 1 will used for the title). However, all of this may change - see issue 18.

  3. The packages used by the notebooks are already installed in the environment into which you will install nbsite.

  4. (optional, for API docs) Any packages for which you want to generate API docs are also installed (which could be via e.g. pip install -e /path/to/pkg).

  5. You are using mac or linux (might work on windows, but currently untested)

  6. You are using holoviews for visualization (other packages might work, or no having holoviews might work, but currently untested; if you don't have holoviews, you will at least need to override nbbuild_ipython_startup in conf.py, setting it to e.g. "").

Installation

conda install -c pyviz nbsite sphinx_ioam_theme or pip install nbsite sphinx_ioam_theme (note: certain operations may require extra dependencies; for now, see setup.py to learn what those are)

One time setup

You can skip and/or modify various steps below depending on what you already have. If you do skip a step, you may need to add something to one of your existing files (should be able to figure that out by looking at the corresponding file in nbsite/tmplate; e.g. if you have existing conf.py you will need to copy in relevant content from nbsite/tmplate/conf.py).

  1. Make a doc dir: mkdir doc && cd doc

  2. Create a set of basic pages: nbsite_from_tmplate.py . (will not overwrite existing files)

  3. Edit conf.py as appropriate for your project.

  4. Edit doc/index.rst toctree to match pages in conf.py

  5. Edit/delete other pages as desired, or add pages. Be sure to update toctrees in index pages as you do this.

  6. Commit initial version of your pages: git commit -m "something" FAQ.rst about.rst conf.py index.rst latest_news.html ... (etc)

Building the site

  1. export MODULE=yourmodule, export ORG=yourorg, export PROJECT=yourproject (or just replace as appropriate in commands below)

  2. (optional, if you want API docs) Generate API docs: nbsite_generate_modules.py ${MODULE} -d ./Reference_Manual -n ${PROJECT} -e tests (assuming you have tests and do not want it to appear in the API docs)

  3. Generate rst containers for notebooks (assuming they are in ../examples: nbsite_nbpagebuild.py ${ORG} ${PROJECT} ../examples .

  4. (optional, if you want gallery) Make the gallery: nbsite_gallery.py ../

  5. Make site: sphinx-build -b html . ./_build/html

  6. Update inter-notebook links: nbsite_fix_links.py _build/html

  7. Do your notebooks need to access local assets such as images? If so, e.g. cp -r ../examples/assets _build/html/.

  8. View the result in a browser at localhost:8000: pushd _build/html && python -m http.server

Re-building/updating the site

rst pages

  • Added, removed, or edited an rst page? Update any toc as necessary (e.g. removing an entry), then re-run step 5 above.

Notebooks

  • Removed a notebook? You have to manually delete the corresponding rst container file.

  • Edited a notebook? Re-run step 5 above. It ought to only re-generate what it needs to (i.e. what's changed), but that probably doesn't work quite yet. You may need to manually remove a 'temp evaluated' notebook and corresponding html file (both from _build/html/path/to/notebook) to have a notebook re-run and turned into html. If you haven't edited the notebook but want it to re-run for another reason e.g. changed dependencies, then you will also need to touch the source notebook.

  • Added a new notebook? Re-run step 3 then proceed as for 'edited', above.

Reference manual

  • If you are working on the reference manual, TODO (depends on commit or not).

Customizing the site

You can customize the style of the site, and you can customize how the IPython notebooks are run.

Style

The html_theme is sphinx_ioam_theme. You may be able to use a different theme (untested). However, you can set the following html_theme_options in conf.py:

  • logo and favicon: provide paths relative to html_static_path (doc/_static by default)
  • custom_css: path relative to html_static_path overriding styles. Styles come first from the theme's main.css (see theme issue), which is extended/overridden by nbsite's own css nbsite/_shared_static/nbsite.css, which can then be further extended/overridden by your site's own css.
  • js TODO

Running of IPython notebooks

In conf.py, you can set options to control notebook execution:

  • nbbuild_cell_timeout: timeout per cell (seconds), e.g. 100
  • nbbuild_ipython_startup: code (as string) to execute before running the first cell of each notebook. Defaults to nbsite's ipython startup code. E.g. "module.special_swith=False".
  • nbbuild_patterns_to_take_along: list of glob patterns to match files that should be copied alongside a notebook. E.g. holoviews is configured to save data in external json files to improve page loading times, so this defaults to ["*.json"].

Automatic deployment to github pages

  1. Remove unnecessary files: nbsite_cleandisthtml.py ./_build/html take_a_chance

  2. Bypass Jekyll on github pages: touch ./_build/html/.nojekyll

  3. Add something like this to your .travis.yml file (but modify for your own preferences):

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: ./_build/html
  on:
    branch: master

See nbsite's .travis.yml for an example.


Right click to download this notebook from GitHub.