jupinx-quickstart

A quickstart utility has been developed to help users get setup quickly with Sphinx, configured in a way to get building collections of Jupyter notebooks quickly.

Installation

To install jupinx:

pip install jupinx

or you can upgrade to the latest version using:

pip install --upgrade jupinx

Note

Windows is currently not tested or supported. See Issue #7

Running jupinx-quickstart

Once, jupinx is installed, to run the jupinx quickstart program you can run:

jupinx-quickstart

on a terminal.

The jupinx-quickstart will:

1. setup a directory structure for your project
2. check for sphinxcontrib-jupyter and sphinxcontrib-bibtex installation
3. construct Makefile and conf.py files
4. construct a parent document source/index.rst
5. setup the project to use the minimal theme

after running the quickstart you may run:

1. make jupyter to build the project as notebooks
2. make website to build the project as a website (via sphinxcontrib-jupyter)
3. make pdf to build the project as a pdf (via sphinxcontrib-jupyter)

Note

The quickstart sets up the Makefile with some conf.py setting overrides to enable building jupyter and website (rather than via a specific builder)

Directory structure

The following directory structure is adopted during the setup:

• ./

  • source: where source RST files should be added
  • source/_static: where _static assets such as figures and images are kept
  • theme: allows you to customise builders using themes and templates
  • Makefile: provides make commands for compiling the project
  • conf.py: provides configuration for sphinx-build

Note

sphinx is quite flexible in setting up a project in a way that suits your workflow. If you want to change directory structure this is likely possible but you will need to update your Makefile after the quickstart is finished. Please refer to sphinx docs for further information.