Contents

Maintenance

Editing the book

There are two ways to edit the book:

1. Edit online: Open to all
2. Edit on a local computer: Only open to project administrators

  • If you don’t already have the bsp-book repository on your computer, then clone the repository

cd /Users/petercharlton/Documents/GitHub/; git clone https://github.com/peterhcharlton/bsp-book

  • If you do already have the repository, then pull the latest version:

cd /Users/petercharlton/Documents/GitHub/bsp-book; git pull https://github.com/peterhcharlton/bsp-book main

  • Make edits to the files on a local computer:

    • cd /Users/petercharlton/Documents/GitHub/bsp-book - make the current directory the repo directory.

    • git checkout -b <branch name> - Creates a new branch on which to make the edits(specified by <branch name>), and makes it the current branch.

    • edit the files (Atom is a helpful text editor for this).

    • git add . - adds all changed files to the staging area.

    • git commit -m "<message describing changes>" - commit the changes to the current branch.

    • git push https://github.com/peterhcharlton/bsp-book <branch name> - pushes the changes to the remote repo on GitHub.

  • Log in to GitHub via a web browser, and go to the repo home page. Assuming you have access, then you should see a message at the top of the page allowing you to create a pull request, to pull the changes from your new branch over to the main branch.

The following are legacy instructions, which may or may not still be required when making changes to a Jupyter notebook:

  • Upload the files through a git push (as detailed here):

cd /Users/petercharlton/Documents/GitHub/bsp-book; git add ./*; git commit -m "brief edit"; git push

  • Build the book locally (as detailed here):

cd /Users/petercharlton/Documents/GitHub/bsp-book/; jupyter-book build --path-output . content

  • Upload the built book to GitHub pages (as detailed here):

cd /Users/petercharlton/Documents/GitHub/bsp-book/; ghp-import -n -p -f _build/html

Recognising contributors

Contributors to the Book who have GitHub accounts can be recognised using the ‘All Contributors’ app (see details here).

Creating the book

The book was created as follows (largely following the instructions provided here):

Steps to create the book:

  1. Install Jupyter book via conda-forge (as detailed here)

  2. Create a template book (as detailed here)

  3. Modify the template to include content from Peter Charlton’s original project guidelines (available here).

  4. Build the book (as detailed here).

  5. Publish the book online (storing the source files in a GitHub repository, and publishing the book using GitHub pages, as detailed here).