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:
- setup a directory structure for your project
- check for
sphinxcontrib-jupyter
andsphinxcontrib-bibtex
installation - construct
Makefile
andconf.py
files - construct a parent document
source/index.rst
- setup the project to use the
minimal
theme
after running the quickstart you may run:
make jupyter
to build the project as notebooksmake website
to build the project as a website (via sphinxcontrib-jupyter)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 addedsource/_static
: where _static assets such as figures and images are kepttheme
: allows you to customise builders using themes and templatesMakefile
: providesmake
commands for compiling the projectconf.py
: provides configuration forsphinx-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.