giswqs / cookiecutter-jupyter-book

Cookiecutter template for a simple jupyter book

Cookiecutter Jupyter Book

A cookiecutter template for creating a simple Jupyter Book. See the rendered version of this cookiecutter template here.

Template

An example template created by this cookiecutter is shown below:

my_book
├── .github
│   └── workflows
│       └── deploy.yml
├── CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── my_book
│   ├── _config.yml
│   ├── _toc.yml
│   ├── fav.ico
│   ├── logo.png
│   ├── bibliography.md
│   ├── markdown.md
│   ├── notebooks.ipynb
│   └── references.bib
├── README.md
├── index.md
└── requirements.txt

Usage

1. Install Cookiecutter if you haven't installed it yet:

$ pip install -U cookiecutter

2. Use cookiecutter-jupyter-book to generate a Jupyter Book template and fill out the requested information (default templating values are shown in square brackets [] and will be used if no other information is entered):

$ cookiecutter gh:giswqs/cookiecutter-jupyter-book

author_name [Captain Jupyter]: Tomas Beuzen
github_or_gitlab_username [tomasbeuzen]:
book_title [My Book]:
repo_name [my-book]:
book_short_description [This cookiecutter creates a simple boilerplate for a Jupyter Book.]: My first Jupyter Book!
version ['0.1.0']:
Select open_source_license:
1 - MIT license
2 - BSD license
3 - ISC license
4 - Apache Software License 2.0
5 - GNU General Public License v3
6 - None
Choose from 1, 2, 3, 4, 5, 6 [1]:
Select include_ci_files:
1 - github
2 - gitlab
3 - no
Choose from 1, 2, 3 [1]:

3. Install the Jupyter Book package requirements from the requirements.txt file (it is recommended to do this in a virtual environment, e.g., using conda):

# Optional steps to create and activate virtual environment
$ conda create --name mybook python=3.9 -y
$ conda activate mybook

$ cd my_book
$ pip install -r requirements.txt

4. Build the HTML render of your Jupyter Book:

$ jupyter-book build my_book/

5. View your rendered book in my_book/_build/html/index.html.

6. Make edits to your book by adding more content, updating the table of contents in my_book/_toc.yml, and and/or by editing the configuration file my_book/_config.yml. See the Jupyter Book documentation for more information on customizing your book.

7. cookiecutter-jupyter-book optionally comes with CI workflow files to help easily deploy your book online. A CI workflow file would have been included in your directory structure if you chose 1 - github or 2 - gitlab for Select include_ci_files: in Step 2 above. For example, if you chose 1 - github, when ready to deploy your book online:

   1. Make sure your book builds locally as expected (jupyter-book build my_book/) and that you have updated the requirements.txt file to include any additional packages required to build your book;

   2. Create a new public GitHub repository to host your book;

   3. Push your local book (including the .github hidden directory) to your GitHub repository. There are many ways to do this, for example:

      $ git init
      $ git add .
      $ git commit -m "first commit"
      $ git remote add origin [e-mail]:<user>/<repository-name>.git
      $ git push -u origin main

   4. The GitHub Actions workflow provided with the cookiecutter (my_book/.github/workflows/deploy.yml) will automatically deploy your book to the gh-pages branch of your repository once pushed. It is typically available after a few minutes at https://<user>.github.io/<myonlinebook>/. You may need to go to the Settings tab of your repository and under the GitHub Pages heading, choose the gh-pages branch from the Source drop-down list. For alternative methods of deploying your book online, see the See the Jupyter Book documentation.

   Note: by default, the GitHub Actions workflow file included with this cookiecutter builds the book with Ubuntu and Python 3.8. You can modify the OS/Python version for the build in the .github/workflows/deploy.yml file on lines 15 and 16 respectively.

   Read more about GitHub Pages and Jupyter Book here, or using GitLab Pages here.

Contributing

We welcome and recognize all contributions. If you'd like to contribute to the project by providing feedback, identifying a bug or working on a new feature, check out the contributing guide to get started.

You can see a list of current contributors in the contributors tab.

Acknowledgements

This template was inspired and made possible by the Cookiecutter project and the Jupyter Book project.