Quickstart

Jupman uses NbSphinx and either ReadTheDocs or Github Actions

Installation

(Instructions are for Ubuntu, on Windows may differ)

First, on Github, fork as a template jupman project to create yours, for example my-project.

Then, on your computer, clone the my-project from Github

You can choose to build either on:

  • ReadTheDocs

  • Github Actions

  • locally with plain Sphinx

  • locally with RTD Docker

(Note Jupman itself is building on both ReadTheDocs and Github Actions only for testing purposes, one is enough)

Building with ReadTheDocs:

IMPORTANT: choose a name which is NOT already on ReadTheDocs

Create a ReadTheDocs account using the same name as in Github so the address in readthedocs will be something like my-project.readthedocs.org.

  • Use ReadTheDocs panels to link the project to your Github repository.

  • In Admin-> Advanced settings panel, set:

    • Python interpreter to CPython 3.x

    • Requirements to requirements-build.txt

Building with Github Actions:

Configure .github/workflows/main.yml on your computer to your needs - you will need to:

  1. at the beginning in the build_docs_job section there is an if which makes the workflow only work in DavidLeoni/jupman repository, change it with your project repo and comment the following needs: run_tests line

  2. set RTD_PRJ_NAME

  3. If you want to publish to Github Pages: everything is set, just create an empty branch gh-pages in an new HTML_FOLDER before committing - from some other folder in your file system:

git clone  YOUR_REPO_ADDRESS  HTML_FOLDER
cd HTML_FOLDER
git checkout --orphan gh-pages
git rm -rf .
touch bla
git add .
git commit -m "init"
git push origin gh-pages

Local build with Sphinx

Assuming you are on Linux/Mac:

  1. Install Python 3.7+

  2. Install Jupyter

  3. Install required modules:

3.a) In a virtual environment (recommended) - from the root of the project, run:

./create-env.sh

This will automatically install required modules in _private/jupman_env using python3 system binary.

If you want to usa a particular python binary (note it must already be on your system), run i.e.:

./create-env.sh python3.7

Afterwards, to activate the environment run:

  • In Windows:

_private\jupman_env\bin\activate

  • in Linux/Mac:

source activate

to deactivate (from anywhere):

deactivate

3.b) without a virtual environment (not recommended): From the root of the project, run:

python3 -m pip install --user -r requirements-build.txt

Warning: to have reproducible builds requirements-build.txt pinpoints a lot of dependencies , installing without virtual environment may mess up other python programs!

Optional - Running tests

To check everything is working, you may want to run the tests.

  1. Install test dependencies:

python3 -m pip install --user -r _test/requirements-test.txt

  1. Run the tests:

python3 -m pytest _test/*_test.py

Optional - Install Jupyter contrib extensions

For a better editing experience like having Table of contents and other things, do the following:

  1. install the Jupyter contrib extensions package:

If you have Anaconda:

conda install -c conda-forge jupyter_contrib_nbextensions

If you don’t have Anaconda:

python3 -m pip install --user jupyter_contrib_nbextensions

  1. Install in Jupyter:

jupyter contrib nbextension install --user

  1. Enable extension:

For being able to view table of contents while editing notebooks, install toc2 extension:

jupyter nbextension enable toc2/main

For tocs to appear when in a document you will need to press a list button at the right-end of the toolbar.

(since Jupman 0.8 custom injected tocs are disabled by default)

  1. For a nice GUI to install extensions, install the Jupyter Nbextensions configurator:

If you have Anaconda:

From Anaconda Prompt:

conda install -c conda-forge jupyter_nbextensions_configurator

If you don’t have Anaconda:

python3 -m pip install --user jupyter_nbextensions_configurator

After installing, enable it:

jupyter nbextensions_configurator enable --user

and then start Jupyter, in file browser look for a Nbextensions tab

Configure

  1. Edit conf.py as needed, which is the configuration file for Sphinx. In particular, you MUST edit the sections marked with TODO

  2. Try launching build:

    python3 build.py

    For more info, see related section

  3. If everything works fine on your computer, push changes back to Github

  4. Go back to ReadTheDocs and try to run a build. Hopefully your project will become available on something like my-project.readthedocs.org

  5. If you want to grade exams, see Exams management page.

You should now be ready to create your notebooks by launching from the project root:

jupyter notebook

  1. If you wish your notebooks to appear in the generated manual, you have to add them in the toc.rst file.

    NOTE: the page toc-page.rst, which is set to be the master_doc of Sphinx, will just load the actual Table of Contents which is in toc.rst. It looks a bit convoluted because when it comes to indexes Sphinx is not much reliable, see this issue . We strongly advise not to change these settings !

  2. edit the home, which is in the index.ipynb file

Building the manual

For a quick build that only produces html:

python3 build.py -q

Site will be created in _build/ folder.

For help:

python3 build.py -h

To build everything (html + pdf + epub), go to the console and from the root directory run:

python3 build.py

NOTE: to generate PDFs you will need to install Latex environment

Publish

Just push to master and Github Actions / ReadTheDocs will do the rest, for example, for jupman is available at addresses:

IMPORTANT: ReadTheDocs WILL *NOT* execute Jupyter notebooks because of this bug

Further steps

See Editing worksheets, Customize and if needed Exams management pages