Get started with Jupyter Book#
This guide is supposed to provide start to end instructions on contributing to this web-based handbook on Windows 10 OS. Feel free to read this out of sequence and focus on the sections that are relevant to you.
Install Git Bash#
Get Anaconda#
At the time of writing this, the Jupyter Book package has been tested with Python 3.8 on Windows 101, with the latest Python version being 3.10.
We will use Anaconda as our package manager to specify which version of Python we want to run on.
Download Anaconda#
To download Anaconda, please visit the Anaconda product page, there you will find the appropriate distribution for your system. Usually, the download prompt shown below should have recognised your system, if not navigate to the bottom of the page or to the Anaconda archive to find the appropriate distribution for your system.
Attention
We have tested downloading on Google Chrome, Microsoft Edge and Firefox Internet Browsers. On Chrome and Edge, it might appear as if the download did not start. However, if you navigate to menu () → downloads you will find the download progressing2.
![../_images/anaconda-webpage-download.jpg](../_images/anaconda-webpage-download.jpg)
The Anaconda download display
Install Anaconda#
Locate the Anaconda installation file, this should be a .exe
file if you are on Windows. Usually, it should be stored, by default settings in your internet browser, in the Downloads folder.
Steps:
Run the installer
Select
Next
Select
I Agree
in the License AgreementSelect
Just Me
when promptedClick
Next
on the Choose Install Location stepWarning
Check that the Destination Folder is on your local drive, usuallly under
C:\Users\<username>\Anaconda3
.
It is recommended that you install Anaconda on your local, i.e. not connected to any network, drive, this is usually theC:
drive for most University of Manchestert managed machines.
If you are using a machine provided by the University of Manchester do not install Anaconda on yourP:
drive or OneDriveDo not add Anaconda to your PATH environment variables (we will do this later)
Check the box prompting you to register Anaconda3 as your default Python 3.9 (optional but recommended unless you’re planning to run multiple package managers)
Wait for Anaconda to finish installing and you are done!
Edit your PATH environment variables#
Begin with your Windows start menu ()
Type in
env
, you should seeEdit the system environment variables
appear as the top optionClick on
Edit the system environment variables
The
System Properties
window should pop up, navigate to theAdvanced
tab, if you’re not already on itAt the bottom click on
Environment Variables...
The
Environment Variables
window should open up, underSystem variables
findPath
Highlight
Path
and clickEdit...
, theEdit environment variable
window should openClick
New
and type the path to your Anaconda3 installation directory, this is usuallyC:\Users\<username>\Anaconda3
Click
OK
to confirm the changes across all windows and you should be set!
Conda on Git Bash#
To check that Anaconda is properly installed on Git Bash follow the steps outlined below:
Open a Git Bash terminal
Type in
conda
and press return ()If you get a menu like the one below then go to step 5, if not follow on from step 4
There are two ways you can proceed with this:
First way:
Open up
.bashrc
with your choice text editor (we will use notepad), this should be located inC:\Users\<username>
If you can not locate you might need to turn on hidden file visibility:
On the top ribbon pane of
File Explorer
head to theView
tab and check the box withHidden items
next to it
In case the file does not exist open up notepad and save an empty file with the name
.bashrc
in yourC:\Users\<username>
directoryType
. /c/Users/<username>/Anaconda3/etc/profile.d/conda.sh
in your.bashrc
file
The second way:
Open up Git Bash and type, replacing
<username>
with yours:echo '. /c/Users/<username>/Anaconda3/etc/profile.d/conda.sh' >> .bashrc
Anaconda sometimes will initialise the (base) environment whenever you open a new Git Bash (or any terminal), to stop this type:
conda config --set auto_activate_base false
You are all set to go!
(Optional) Pick your favourite IDE#
Integrated Development Environments (IDE) can be a very personal thing. Over the years some of the people on our team have used several setups from PyCharm and RStudio, to text editors such as Sublime Text accompanied by a detached terminal window3. For what we demonstrate here we will use Visual Studio Code. If you are comfortable with your set up we do not recommend you change anything.
Install the Jupyter Book Environment#
Download and install the environment#
Download the Jupyter Book environment by picture below, right-click and select Save link as...
:
Anaconda Environment
Start up
Anaconda Navigator
(depending on your system this might take some time and open a few dialog boxes)On the left-hand pane navigate to
Environments
(you might have to wait a bit again)Next to the menu pane you will see the environments list, at the bottom you will see a menu with environment creating options, click
Import
An animation showing step 4-7 can be found below
Choose to Import from: your
Local drive
Find the location where you saved the environment you saved from this page
(Optional) Specify a New environment name:
Click on Import and you are done, you just have to wait for all the packages to download
![../_images/anaconda-env.gif](../_images/anaconda-env.gif)
Check that your environment works#
The steps outlined below will help you check if you have installed the environment correctly:
Open up your Terminal application, we will use Git Bash to demonstrate
Type the following into your terminal application replacing
your-env-name
with the name you have defined for your environment:conda activate your-env-name
If you see your defined environment name above the terminal location enclosed by parentheses then your environment specification has worked!
(Bonus) Type the following to deactivate the environment:
conda deactivate
Check that Jupyter Book works#
You should have now have successfully installed all you need to get started with Jupyter Book, as outlined above. We will follow a simple exercise to test whether it runs on your machine.
Open up a terminal and activate your environment as outlines in steps 1 - 3 above, and type in the code below, press return () and the Jupyter Book help menu should show appear:
jupyter-book
![../_images/check-jb-install.gif](../_images/check-jb-install.gif)
Clone the Repo and start contributing#
You can find a condensed version in the README accompanying the repository this handbook is hosted on.
Warning
The guide below assumes you have some familiarity with Git and branching.
If not you are not familiar with Git please follow one of the guides we recommend here.
A more in-depth version of steps 3 - 7 can be found on the next page.
Follow these steps to clone the repository to your local drive and push updates:
Depending on if you have set up SSH-keys on your machine, or not, choose how you want to clone the repository on the page under the green
Code
button Code and press the clone () button to copy the line to your clipboardHint
The most straightforward way is via HTTPS
Decided on a location (2 ways):
Open up a terminal window and navigate to a directory you want to store this book in
ORNavigate to the directory (in File Explorer) you want to store this book in, right-click, and select
Git Bash here
Type in, replacing
<text-you-copied>
with the actual text you copied:git clone <text-you-copied>
Create a new branch to push your updates from
Initialise your Jupyter Book environment
Type in:
jupyter-book build handbook/
Push your updates to the repository
A workflow for contributing#
We will discuss the workflow to push updates in the next page
- 1
Of course you can bypass most of this guide and use the Linux Subsystem on Windows and if you prefer
pip
as your package and virtual environment manager.- 2
We are not able to test this on the Safari web browser, currently. If you are able to help feel free to contribute to this guide.
- 3
If you want to play around with different text editors, GitHub maintains a list of free open-source text editors here, and you can find some more information on Wikipedia here.