├── .github └── workflows │ ├── deploy.yml │ └── tests.yml ├── CHANGELOG.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── cookiecutter.json ├── hooks └── post_gen_project.py ├── requirements.txt ├── tests └── test_cookiecutter.py └── {{cookiecutter.book_slug}} ├── .github └── workflows │ └── deploy.yml ├── .gitlab-ci.yml ├── CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── requirements.txt └── {{cookiecutter.book_slug}} ├── _config.yml ├── _toc-legacy.yml ├── _toc.yml ├── content.md ├── intro.md ├── logo.png ├── markdown-notebooks.md ├── markdown.md ├── notebooks.ipynb └── references.bib /.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: deploy-book 2 | 3 | on: 4 | # Trigger the deploy on push to main branch 5 | push: 6 | branches: 7 | - main 8 | 9 | env: 10 | BASE_URL: /${{ github.event.repository.name }} 11 | 12 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. 13 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. 14 | concurrency: 15 | group: "pages" 16 | cancel-in-progress: false 17 | 18 | jobs: 19 | deploy-book: 20 | runs-on: ubuntu-latest 21 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 22 | permissions: 23 | pages: write 24 | id-token: write 25 | steps: 26 | - uses: actions/checkout@v4 27 | 28 | # Install dependencies 29 | - name: Set up Python 3.11 30 | uses: actions/setup-python@v5 31 | with: 32 | python-version: "3.11" 33 | cache: pip # Implicitly depends upon requirements.txt 34 | 35 | - name: Install dependencies 36 | run: pip install -r requirements.txt 37 | 38 | # Use default CC 39 | - name: Cookiecutter no GHA 40 | run: cookiecutter . --no-input include_ci=no 41 | 42 | # Install requirements.txt 43 | - name: Install requirements 44 | run: pip install -r my_book/requirements.txt 45 | 46 | # Build the example book 47 | - name: Build book 48 | run: jupyter-book build my_book/my_book/ 49 | 50 | # Upload the book's HTML as an artifact 51 | - name: Upload artifact 52 | uses: actions/upload-pages-artifact@v3 53 | with: 54 | path: "my_book/my_book/_build/html" 55 | 56 | # Deploy the book's HTML to GitHub Pages 57 | - name: Deploy to GitHub Pages 58 | id: deployment 59 | uses: actions/deploy-pages@v4 60 | -------------------------------------------------------------------------------- /.github/workflows/tests.yml: -------------------------------------------------------------------------------- 1 | name: tests 2 | 3 | on: 4 | # Trigger the workflow on push or pull request on main branch 5 | push: 6 | branches: 7 | - main 8 | pull_request: 9 | branches: 10 | - main 11 | schedule: 12 | # Run cron job every month, https://crontab.guru/every-month 13 | - cron: '0 0 1 * *' 14 | workflow_dispatch: 15 | 16 | jobs: 17 | # This job tests that the CC works 18 | test-cc-and-jb-build: 19 | runs-on: ubuntu-latest 20 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 21 | permissions: 22 | pages: write 23 | id-token: write 24 | steps: 25 | - uses: actions/checkout@v3 26 | 27 | # Install dependencies 28 | - name: Set up Python 3.11 29 | uses: actions/setup-python@v4 30 | with: 31 | python-version: 3.11 32 | - name: Install dependencies 33 | run: | 34 | pip install -r requirements.txt 35 | # Use the default CC 36 | - name: Check black style 37 | run: | 38 | black ./ --check 39 | # Run tests 40 | - name: Pytest tests 41 | run: | 42 | pytest 43 | # Use default CC 44 | - name: Cookiecutter no GHA 45 | run: | 46 | cookiecutter . --no-input --overwrite-if-exists include_ci=no 47 | # Install requirements.txt 48 | - name: Install requirements 49 | run: | 50 | pip install -r my_book/requirements.txt 51 | # Build the example book 52 | - name: Build book 53 | run: | 54 | jupyter-book build my_book/my_book/ 55 | # Upload the book's HTML as an artifact 56 | - name: Upload artifact 57 | uses: actions/upload-pages-artifact@v2 58 | with: 59 | path: "my_book/my_book/_build/html" 60 | # Deploy the book's HTML to GitHub Pages 61 | - name: Deploy to GitHub Pages 62 | id: deployment 63 | uses: actions/deploy-pages@v2 -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Change Log 2 | 3 | ## v0.8 2020-05-29 4 | 5 | - 🔧 MAINTAIN: support new toc format (@TomasBeuzen) (PR: #26) 6 | - 🔧 MAINTAIN: update templating files from Jupyter Book repo (@TomasBeuzen) (PR: #24) 7 | 8 | ## v0.7 2020-10-02 9 | 10 | - 🔧 MAINTAIN: change "master" to "main" for this repo and all CC templates (@TomasBeuzen) (PR: #22) 11 | 12 | ## v0.6 2020-10-02 13 | 14 | General improvement to the repo in this version, with updated docs and new tests. We've also added preliminary support for GitLab CI. 15 | 16 | - ✨ NEW: CC now includes a `.gitlab-ci.yml` (thanks @slemonide & acknowledgements to @bsamadi for the source file) (PR: #9) 17 | - ✨ NEW: adding new test regime using pytest (@TomasBeuzen) (PR: #19) 18 | - ✨ NEW: validate entered github username on github.com (@TomasBeuzen) (PR: #5) 19 | 20 | - 👌 IMPROVE: CC is now more host-agnostic, supporting both GitHub and GitLab, with various changes to the .json file and post-gen script. The goal is to improve support fot GitLab as its support in JupyterBook grows (PR: ) 21 | - 👌 IMPROVE: add "None" option to licenses (@TomasBeuzen) (PR: #17) 22 | - 👌 IMPROVE: change "full_name" to "author_name" in CC json for clarity (@TomasBeuzen) (PR: #2) 23 | 24 | - 🐛 FIX: bad reference in LICENSE (@TomasBeuzen) (PR: #16) 25 | - 🐛 FIX: Need to have `-r` when installing from requirements.txt (@slemonide) (PR: #8) 26 | 27 | - 🔧 MAINTAIN: update book template to latest Jupyter Book files (@TomasBeuzen) (PR: #11) 28 | 29 | - 📚 DOCS: update contributing docs (@TomasBeuzen) (PR: #6, #16) 30 | - 📚 DOCS: fix typo in markdown.md (@westurner) (PR: #12) 31 | - 📚 DOCS: add changelog (@TomasBeuzen) (PR: #20) 32 | 33 | ## v0.1 - v0.5 34 | 35 | - Preliminary works 36 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | 2 | # Contributing 3 | 4 | Contributions are welcome, and they are greatly appreciated! Every little bit 5 | helps, and credit will always be given. 6 | 7 | You can contribute in many ways: 8 | 9 | ## Types of Contributions 10 | 11 | ### Report Bugs, Request Features or Submit Feedback 12 | 13 | Report bugs as a [GitHub issue](https://github.com/executablebooks/cookiecutter-jupyter-book/issues). 14 | 15 | If you are reporting a bug, please include: 16 | 17 | * Your operating system name and version. 18 | * Any details about your local setup that might be helpful in troubleshooting. 19 | * Detailed steps to reproduce the bug. 20 | 21 | If you are proposing a feature, please include: 22 | 23 | * Explain in detail how it would work. 24 | * Keep the scope as narrow as possible, to make it easier to implement. 25 | * Remember that this is a volunteer-driven project, and that contributions 26 | are welcome :) 27 | 28 | ### Improvements 29 | 30 | Look through the (https://github.com/executablebooks/cookiecutter-jupyter-book/issues) for bugs, feature requests, etc and feel free to contribute! 31 | 32 | ## Get Started 33 | 34 | Ready to contribute? Here's how to set up `cookiecutter-jupyter-book` for local development. 35 | 36 | 1. Fork the `cookiecutter-jupyter-book` repo on GitHub. 37 | 2. Clone your fork locally and install requirements: 38 | 39 | ```sh 40 | git clone git@github.com:your_name_here/cookiecutter-jupyter-book.git 41 | pip install -r requirements.txt 42 | ``` 43 | 44 | 3. Create a branch for local development: 45 | 46 | ```sh 47 | git checkout -b name-of-your-bugfix-or-feature 48 | ``` 49 | 50 | 4. Make your desired changes, run tests, and push your branch to GitHub when you're ready: 51 | 52 | ```sh 53 | pytest 54 | black ./ --check 55 | git add . 56 | git commit -m "Your detailed description of your changes." 57 | git push origin name-of-your-bugfix-or-feature 58 | ``` 59 | 60 | 5. Open a pull request through the GitHub website. Naming convention for pull requests is [detailed here](https://github.com/executablebooks/.github/blob/main/CONTRIBUTING.md#commit-messages). For example, a pull request that adds a new feature might be titled: `✨ NEW: validate entered github username`. -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | BSD 3-Clause License 2 | 3 | Copyright (c) 2020, Tomas Beuzen 4 | All rights reserved. 5 | 6 | Redistribution and use in source and binary forms, with or without 7 | modification, are permitted provided that the following conditions are met: 8 | 9 | 1. Redistributions of source code must retain the above copyright notice, this 10 | list of conditions and the following disclaimer. 11 | 12 | 2. Redistributions in binary form must reproduce the above copyright notice, 13 | this list of conditions and the following disclaimer in the documentation 14 | and/or other materials provided with the distribution. 15 | 16 | 3. Neither the name of the copyright holder nor the names of its 17 | contributors may be used to endorse or promote products derived from 18 | this software without specific prior written permission. 19 | 20 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 23 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 24 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 26 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 27 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Cookiecutter Jupyter Book 2 | 3 | ![tests](https://github.com/executablebooks/cookiecutter-jupyter-book/workflows/tests/badge.svg) 4 | ![deploy](https://github.com/executablebooks/cookiecutter-jupyter-book/workflows/deploy/badge.svg) 5 | [![release](https://img.shields.io/github/release/executablebooks/cookiecutter-jupyter-book.svg)](https://github.com/executablebooks/cookiecutter-jupyter-book/releases) 6 | [![python](https://img.shields.io/badge/python-3.8%2C%203.9%2C%203.10-blue)]() 7 | [![os](https://img.shields.io/badge/OS-Ubuntu%2C%20Mac%2C%20Windows-yellow)]() 8 | 9 |

10 | 11 |

12 | 13 | A cookiecutter template for creating a simple [Jupyter Book](https://jupyterbook.org/intro.html). See the rendered version of this cookiecutter template [here](https://executablebooks.github.io/cookiecutter-jupyter-book/). 14 | 15 | ## Template 16 | 17 | An example template created by this cookiecutter is shown below: 18 | 19 | ``` 20 | my_book 21 | ├── .github 22 | │ └── workflows 23 | │ └── deploy.yml 24 | ├── CONDUCT.md 25 | ├── CONTRIBUTING.md 26 | ├── LICENSE 27 | ├── my_book 28 | │ ├── _config.yml 29 | │ ├── _toc.yml 30 | │ ├── content.md 31 | │ ├── intro.md 32 | │ ├── logo.png 33 | │ ├── markdown.md 34 | │ ├── markdown-notebooks.md 35 | │ ├── notebooks.ipynb 36 | │ └── references.bib 37 | ├── README.md 38 | └── requirements.txt 39 | ``` 40 | 41 | ## Usage 42 | 43 | 1. Install [Cookiecutter](https://github.com/cookiecutter/cookiecutter/tree/1.7.2) if you haven't installed it yet: 44 | 45 | ```bash 46 | $ pip install -U cookiecutter jupyter-book 47 | ``` 48 | 49 | 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): 50 | 51 | ```bash 52 | $ cookiecutter git@github.com:executablebooks/cookiecutter-jupyter-book.git 53 | 54 | author_name [Captain Jupyter]: Tomas Beuzen 55 | github_username [tomasbeuzen]: 56 | book_name [My Book]: 57 | book_slug [my_book]: 58 | book_short_description [This cookiecutter creates a simple boilerplate for a Jupyter Book.]: My first Jupyter Book! 59 | version ['0.1.0']: 60 | Select open_source_license: 61 | 1 - MIT license 62 | 2 - BSD license 63 | 3 - Apache Software License 2.0 64 | 4 - CC BY 4.0 65 | 5 - CC BY-SA 4.0 66 | 6 - None 67 | Choose from 1, 2, 3, 4, 5, 6 [1]: 68 | Select include_ci: 69 | 1 - github 70 | 2 - gitlab 71 | 3 - no 72 | Choose from 1, 2, 3 [1]: 73 | ``` 74 | 75 | 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](https://docs.conda.io/en/latest/)): 76 | 77 | ```bash 78 | # Optional steps to create and activate virtual environment 79 | $ conda create --name mybook python=3.8 -y 80 | $ conda activate mybook 81 | ``` 82 | 83 | ```bash 84 | $ cd my_book 85 | $ pip install -r requirements.txt 86 | ``` 87 | 88 | 4. Build the HTML render of your Jupyter Book: 89 | 90 | ```bash 91 | $ jupyter-book build my_book/ 92 | ``` 93 | 94 | 5. View your rendered book in `my_book/_build/html/index.html`. 95 | 96 | 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](https://jupyterbook.org/intro.html) for more information on customizing your book. 97 | 98 | 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: 99 | 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; 100 | 2. Create a new public [GitHub repository](https://github.com/new) to host your book; 101 | 3. Push your local book (including the `.github` hidden directory) to your GitHub repository. There are many ways to do this, for example: 102 | 103 | ```bash 104 | $ git init 105 | $ git add . 106 | $ git commit -m "first commit" 107 | $ git remote add origin git@github.com:/.git 108 | $ git push -u origin main 109 | ``` 110 | 111 | 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://.github.io//`. 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](https://jupyterbook.org/intro.html). 112 | 113 | > 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. 114 | 115 | > Read more about GitHub Pages and Jupyter Book [here](https://jupyterbook.org/publish/gh-pages.html#automatically-host-your-book-with-github-actions), or using GitLab Pages [here](https://docs.gitlab.com/ee/user/project/pages/getting_started/pages_from_scratch.html). 116 | 117 | ## Contributing 118 | 119 | 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](CONTRIBUTING.md) to get started. 120 | 121 | You can see a list of current contributors in the [contributors tab](https://github.com/executablebooks/cookiecutter-jupyter-book/graphs/contributors). 122 | 123 | ## Acknowledgements 124 | 125 | This template was inspired and made possible by the [Cookiecutter project](https://github.com/cookiecutter/cookiecutter) and the [Jupyter Book project](https://github.com/executablebooks/jupyter-book). 126 | -------------------------------------------------------------------------------- /cookiecutter.json: -------------------------------------------------------------------------------- 1 | { 2 | "author_name": "Captain Jupyter", 3 | "github_username": "{{ cookiecutter.author_name.lower().replace(' ', '') }}", 4 | "book_name": "My Book", 5 | "book_slug": "{{ cookiecutter.book_name.lower().replace(' ', '_').replace('-', '_') }}", 6 | "book_short_description": "This cookiecutter creates a simple boilerplate for a Jupyter Book.", 7 | "version": "'0.1.0'", 8 | "open_source_license": [ 9 | "MIT license", 10 | "BSD license", 11 | "Apache Software License 2.0", 12 | "CC BY 4.0", 13 | "CC BY-SA 4.0", 14 | "None" 15 | ], 16 | "include_ci": [ 17 | "github", 18 | "gitlab", 19 | "no" 20 | ] 21 | } -------------------------------------------------------------------------------- /hooks/post_gen_project.py: -------------------------------------------------------------------------------- 1 | # This script cleans up github workflows post CC generation 2 | import os 3 | import shutil 4 | import requests 5 | import jupyter_book 6 | from textwrap import dedent 7 | 8 | ############################################################################## 9 | # Path utilities 10 | 11 | 12 | def remove(filepath): 13 | if os.path.isfile(filepath): 14 | os.remove(filepath) 15 | elif os.path.isdir(filepath): 16 | shutil.rmtree(filepath) 17 | 18 | 19 | def rename(current_filepath, new_filepath): 20 | if os.path.isfile(current_filepath): 21 | os.rename(current_filepath, new_filepath) 22 | 23 | 24 | ############################################################################## 25 | # CLI utilities 26 | 27 | border = "=" * 79 28 | endc = "\033[0m" 29 | bcolors = dict( 30 | blue="\033[94m", 31 | green="\033[92m", 32 | orange="\033[93m", 33 | red="\033[91m", 34 | bold="\033[1m", 35 | underline="\033[4m", 36 | ) 37 | 38 | 39 | def _color_message(msg, style): 40 | return bcolors[style] + msg + endc 41 | 42 | 43 | def _message_box(msg, color="green", doprint=True, print_func=print): 44 | # Prepare the message so the indentation is the same as the box 45 | msg = dedent(msg) 46 | 47 | # Color and create the box 48 | border_colored = _color_message(border, color) 49 | box = """ 50 | {border_colored} 51 | {msg} 52 | {border_colored} 53 | """ 54 | box = dedent(box).format(msg=msg, border_colored=border_colored) 55 | if doprint is True: 56 | print_func(box) 57 | return box 58 | 59 | 60 | ############################################################################## 61 | # Post-gen script 62 | 63 | github = "{{cookiecutter.include_ci}}" == "github" 64 | gitlab = "{{cookiecutter.include_ci}}" == "gitlab" 65 | license = "{{cookiecutter.open_source_license}}" == "None" 66 | version = jupyter_book.__version__ 67 | 68 | # Remove CI 69 | if github: 70 | remove(".gitlab-ci.yml") 71 | elif gitlab: 72 | remove(".github/") 73 | else: 74 | # remove all CI 75 | remove(".github/") 76 | remove(".gitlab-ci.yml") 77 | 78 | 79 | # Remove license 80 | if license: 81 | remove("LICENSE") 82 | 83 | 84 | # Legacy support for old JB ToC format 85 | if version < "0.11.0": 86 | remove("{{cookiecutter.book_slug}}/_toc.yml") 87 | rename( 88 | "{{cookiecutter.book_slug}}/_toc-legacy.yml", 89 | "{{cookiecutter.book_slug}}/_toc.yml", 90 | ) 91 | else: 92 | remove("{{cookiecutter.book_slug}}/_toc-legacy.yml") 93 | 94 | 95 | # Check existence of GitHub user, else raise warning 96 | if ( 97 | not requests.get( 98 | "http://www.github.com/{{cookiecutter.github_username}}" 99 | ).status_code 100 | < 400 101 | ): 102 | _message_box( 103 | "WARNING:\n" 104 | "Could not find the user '{{cookiecutter.github_username}}' on github.com.\n" 105 | "Please check the 'github_username' you entered.\n" 106 | "If you are not using github.com you may ignore this warning.", 107 | color="orange", 108 | ) 109 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | jupyter-book 2 | cookiecutter 3 | pytest 4 | black -------------------------------------------------------------------------------- /tests/test_cookiecutter.py: -------------------------------------------------------------------------------- 1 | import json 2 | import subprocess 3 | from pathlib import Path 4 | from itertools import product 5 | from pytest import fixture, mark 6 | 7 | IGNORE = [".DS_Store", "__pycache__"] 8 | 9 | 10 | @fixture() 11 | def base_command(tmpdir): 12 | return (f"cookiecutter . --no-input --output-dir {tmpdir}", tmpdir) 13 | 14 | 15 | def num_items(path, directory=[""]): 16 | files = [ 17 | file for file in path.joinpath(*directory).iterdir() if file.name not in IGNORE 18 | ] 19 | return len(files) 20 | 21 | 22 | def test_cookiecutter_default_options(base_command): 23 | result = subprocess.run(base_command[0], shell=True) 24 | assert result.returncode == 0 25 | 26 | 27 | with open("cookiecutter.json") as f: 28 | options = json.load(f) 29 | combinations = list(product(options["open_source_license"], options["include_ci"])) 30 | 31 | 32 | @mark.parametrize("open_source_license,include_ci", combinations) 33 | def test_cookiecutter_all_options(base_command, open_source_license, include_ci): 34 | params = f" open_source_license='{open_source_license}' include_ci={include_ci}" 35 | path = Path(base_command[1]) 36 | result = subprocess.run(base_command[0] + params, shell=True) 37 | assert result.returncode == 0 38 | assert num_items(path, ["my_book", "my_book"]) == 9 39 | if open_source_license == "None": 40 | if include_ci == "github": 41 | assert num_items(path, ["my_book", ".github", "workflows"]) == 1 42 | assert num_items(path, ["my_book"]) == 6 43 | elif include_ci == "gitlab": 44 | assert num_items(path, ["my_book"]) == 6 45 | else: 46 | assert num_items(path, ["my_book"]) == 5 47 | else: 48 | if include_ci == "github": 49 | assert num_items(path, ["my_book", ".github", "workflows"]) == 1 50 | assert num_items(path, ["my_book"]) == 7 51 | elif include_ci == "gitlab": 52 | assert num_items(path, ["my_book"]) == 7 53 | else: 54 | assert num_items(path, ["my_book"]) == 6 55 | 56 | 57 | def test_jupyter_book_cookiecutter(base_command): 58 | # same tests being run in the Jupyter Book test regime 59 | # https://github.com/executablebooks/jupyter-book/blob/main/tests/test_build.py#L26-L35 60 | # default cookiecutter book name is "my_book" 61 | path = Path(base_command[1]) 62 | result = subprocess.run(base_command[0], shell=True) 63 | assert result.returncode == 0 64 | assert path.joinpath("my_book", "my_book", "_config.yml").exists() 65 | assert num_items(path, ["my_book"]) == 7 66 | assert num_items(path, ["my_book", ".github", "workflows"]) == 1 67 | assert num_items(path, ["my_book", "my_book"]) == 9 68 | 69 | 70 | @mark.parametrize( 71 | "username,service,msg", 72 | [ 73 | ("fake_captainjupyter_fake", "github", "WARNING"), 74 | ("fake_captainjupyter_fake", "gitlab", "WARNING"), 75 | ], 76 | ) 77 | def test_warning_message(base_command, username, service, msg): 78 | result = subprocess.run( 79 | base_command[0] + f" include_ci={service}", 80 | shell=True, 81 | capture_output=True, 82 | ) 83 | assert result.returncode == 0 84 | assert msg in result.stdout.decode("ascii") 85 | -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: deploy-book 2 | 3 | on: 4 | # Trigger the workflow on push to main branch 5 | push: 6 | branches: 7 | - main 8 | 9 | env: 10 | BASE_URL: {% raw %}/${{ github.event.repository.name }}{% endraw %} 11 | 12 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. 13 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. 14 | concurrency: 15 | group: "pages" 16 | cancel-in-progress: false 17 | 18 | jobs: 19 | deploy-book: 20 | runs-on: ubuntu-latest 21 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 22 | permissions: 23 | pages: write 24 | id-token: write 25 | steps: 26 | - uses: actions/checkout@v4 27 | 28 | # Install dependencies 29 | - name: Set up Python 3.11 30 | uses: actions/setup-python@v5 31 | with: 32 | python-version: "3.11" 33 | cache: pip # Implicitly depends upon requirements.txt 34 | 35 | - name: Install dependencies 36 | run: pip install -r requirements.txt 37 | 38 | # Build the book 39 | - name: Build the book 40 | run: jupyter-book build {{cookiecutter.book_slug}} 41 | 42 | # Upload the book's HTML as an artifact 43 | - name: Upload artifact 44 | uses: actions/upload-pages-artifact@v3 45 | with: 46 | path: "{{cookiecutter.book_slug}}/_build/html" 47 | 48 | # Deploy the book's HTML to GitHub Pages 49 | - name: Deploy to GitHub Pages 50 | id: deployment 51 | uses: actions/deploy-pages@v4 52 | -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/.gitlab-ci.yml: -------------------------------------------------------------------------------- 1 | image: python:3.11 2 | 3 | # Change pip's cache directory to be inside the project directory since we can 4 | # only cache local items. 5 | variables: 6 | PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" 7 | 8 | # Pip's cache doesn't store the python packages 9 | # https://pip.pypa.io/en/stable/reference/pip_install/#caching 10 | # 11 | # If you want to also cache the installed packages, you have to install 12 | # them in a virtualenv and cache it as well. 13 | cache: 14 | paths: 15 | - .cache/pip 16 | - venv/ 17 | 18 | before_script: 19 | - python -V # Print out python version for debugging 20 | - pip install virtualenv 21 | - virtualenv venv 22 | - source venv/bin/activate 23 | 24 | pages: 25 | script: 26 | - pip install -r requirements.txt 27 | - jupyter-book build {{ cookiecutter.book_slug }} 28 | - mv {{ cookiecutter.book_slug }}/_build/html/ public/ 29 | artifacts: 30 | paths: 31 | - public 32 | only: 33 | - main 34 | 35 | workflow: 36 | rules: 37 | - if: $CI_COMMIT_REF_NAME =~ /-wip$/ # Pipelines for branch or tag names that include -wip don't run 38 | when: never 39 | - if: '$CI_PIPELINE_SOURCE == "push"' 40 | -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/CONDUCT.md: -------------------------------------------------------------------------------- 1 | 2 | # Code of Conduct 3 | 4 | ## Our Pledge 5 | 6 | In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. 7 | 8 | ## Our Standards 9 | 10 | Examples of behavior that contributes to creating a positive environment include: 11 | 12 | * Using welcoming and inclusive language 13 | * Being respectful of differing viewpoints and experiences 14 | * Gracefully accepting constructive criticism 15 | * Focusing on what is best for the community 16 | * Showing empathy towards other community members 17 | 18 | Examples of unacceptable behavior by participants include: 19 | 20 | * The use of sexualized language or imagery and unwelcome sexual attention or advances 21 | * Trolling, insulting/derogatory comments, and personal or political attacks 22 | * Public or private harassment 23 | * Publishing others' private information, such as a physical or electronic address, without explicit permission 24 | * Other conduct which could reasonably be considered inappropriate in a professional setting 25 | 26 | ## Our Responsibilities 27 | 28 | Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. 29 | 30 | Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. 31 | 32 | ## Scope 33 | 34 | This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. 35 | 36 | ## Enforcement 37 | 38 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. 39 | 40 | Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. 41 | 42 | ## Attribution 43 | 44 | This Code of Conduct is adapted from the [Contributor Covenant, version 1.4](http://contributor-covenant.org/version/1/4). 45 | -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Contributions are welcome, and they are greatly appreciated! Every little bit 4 | helps, and credit will always be given. You can contribute in the ways listed below. 5 | 6 | ## Report Bugs 7 | 8 | Report bugs using GitHub issues. 9 | 10 | If you are reporting a bug, please include: 11 | 12 | * Your operating system name and version. 13 | * Any details about your local setup that might be helpful in troubleshooting. 14 | * Detailed steps to reproduce the bug. 15 | 16 | ## Fix Bugs 17 | 18 | Look through the GitHub issues for bugs. Anything tagged with "bug" and "help 19 | wanted" is open to whoever wants to implement it. 20 | 21 | ## Implement Features 22 | 23 | Look through the GitHub issues for features. Anything tagged with "enhancement" 24 | and "help wanted" is open to whoever wants to implement it. 25 | 26 | ## Write Documentation 27 | 28 | {{ cookiecutter.book_name }} could always use more documentation, whether as part of the 29 | official {{ cookiecutter.book_name }} docs, in docstrings, or even on the web in blog posts, 30 | articles, and such. 31 | 32 | ## Submit Feedback 33 | 34 | The best way to send feedback is to file an issue on GitHub. 35 | 36 | If you are proposing a feature: 37 | 38 | * Explain in detail how it would work. 39 | * Keep the scope as narrow as possible, to make it easier to implement. 40 | * Remember that this is a volunteer-driven project, and that contributions 41 | are welcome :) 42 | 43 | ## Get Started 44 | 45 | Ready to contribute? Here's how to set up `{{ cookiecutter.book_name }}` for local development. 46 | 47 | 1. Fork the repo on GitHub. 48 | 2. Clone your fork locally. 49 | 3. Install your local copy into a virtualenv, e.g., using `conda`. 50 | 4. Create a branch for local development and make changes locally. 51 | 5. Commit your changes and push your branch to GitHub. 52 | 6. Submit a pull request through the GitHub website. 53 | 54 | ## Code of Conduct 55 | 56 | Please note that the {{ cookiecutter.book_name }} project is released with a [Contributor Code of Conduct](CONDUCT.md). By contributing to this project you agree to abide by its terms. 57 | -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/LICENSE: -------------------------------------------------------------------------------- 1 | {% if cookiecutter.open_source_license == 'MIT license' -%} 2 | MIT License 3 | 4 | Copyright (c) {% now 'local', '%Y' %}, {{ cookiecutter.author_name }} 5 | 6 | Permission is hereby granted, free of charge, to any person obtaining a copy 7 | of this software and associated documentation files (the "Software"), to deal 8 | in the Software without restriction, including without limitation the rights 9 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | copies of the Software, and to permit persons to whom the Software is 11 | furnished to do so, subject to the following conditions: 12 | 13 | The above copyright notice and this permission notice shall be included in all 14 | copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 | SOFTWARE. 23 | {% elif cookiecutter.open_source_license == 'BSD license' %}BSD License 24 | 25 | Copyright (c) {% now 'local', '%Y' %}, {{ cookiecutter.author_name }} 26 | All rights reserved. 27 | 28 | Redistribution and use in source and binary forms, with or without modification, 29 | are permitted provided that the following conditions are met: 30 | 31 | * Redistributions of source code must retain the above copyright notice, this 32 | list of conditions and the following disclaimer. 33 | 34 | * Redistributions in binary form must reproduce the above copyright notice, this 35 | list of conditions and the following disclaimer in the documentation and/or 36 | other materials provided with the distribution. 37 | 38 | * Neither the name of the copyright holder nor the names of its 39 | contributors may be used to endorse or promote products derived from this 40 | software without specific prior written permission. 41 | 42 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 43 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 44 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 45 | IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 46 | INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 47 | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 48 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 49 | OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 50 | OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51 | OF THE POSSIBILITY OF SUCH DAMAGE. 52 | {% elif cookiecutter.open_source_license == 'CC BY 4.0' -%}Attribution 4.0 International 53 | 54 | ======================================================================= 55 | 56 | Creative Commons Corporation ("Creative Commons") is not a law firm and 57 | does not provide legal services or legal advice. Distribution of 58 | Creative Commons public licenses does not create a lawyer-client or 59 | other relationship. Creative Commons makes its licenses and related 60 | information available on an "as-is" basis. Creative Commons gives no 61 | warranties regarding its licenses, any material licensed under their 62 | terms and conditions, or any related information. Creative Commons 63 | disclaims all liability for damages resulting from their use to the 64 | fullest extent possible. 65 | 66 | Using Creative Commons Public Licenses 67 | 68 | Creative Commons public licenses provide a standard set of terms and 69 | conditions that creators and other rights holders may use to share 70 | original works of authorship and other material subject to copyright 71 | and certain other rights specified in the public license below. The 72 | following considerations are for informational purposes only, are not 73 | exhaustive, and do not form part of our licenses. 74 | 75 | Considerations for licensors: Our public licenses are 76 | intended for use by those authorized to give the public 77 | permission to use material in ways otherwise restricted by 78 | copyright and certain other rights. Our licenses are 79 | irrevocable. Licensors should read and understand the terms 80 | and conditions of the license they choose before applying it. 81 | Licensors should also secure all rights necessary before 82 | applying our licenses so that the public can reuse the 83 | material as expected. Licensors should clearly mark any 84 | material not subject to the license. This includes other CC- 85 | licensed material, or material used under an exception or 86 | limitation to copyright. More considerations for licensors: 87 | wiki.creativecommons.org/Considerations_for_licensors 88 | 89 | Considerations for the public: By using one of our public 90 | licenses, a licensor grants the public permission to use the 91 | licensed material under specified terms and conditions. If 92 | the licensor's permission is not necessary for any reason--for 93 | example, because of any applicable exception or limitation to 94 | copyright--then that use is not regulated by the license. Our 95 | licenses grant only permissions under copyright and certain 96 | other rights that a licensor has authority to grant. Use of 97 | the licensed material may still be restricted for other 98 | reasons, including because others have copyright or other 99 | rights in the material. A licensor may make special requests, 100 | such as asking that all changes be marked or described. 101 | Although not required by our licenses, you are encouraged to 102 | respect those requests where reasonable. More considerations 103 | for the public: 104 | wiki.creativecommons.org/Considerations_for_licensees 105 | 106 | ======================================================================= 107 | 108 | Creative Commons Attribution 4.0 International Public License 109 | 110 | By exercising the Licensed Rights (defined below), You accept and agree 111 | to be bound by the terms and conditions of this Creative Commons 112 | Attribution 4.0 International Public License ("Public License"). To the 113 | extent this Public License may be interpreted as a contract, You are 114 | granted the Licensed Rights in consideration of Your acceptance of 115 | these terms and conditions, and the Licensor grants You such rights in 116 | consideration of benefits the Licensor receives from making the 117 | Licensed Material available under these terms and conditions. 118 | 119 | 120 | Section 1 -- Definitions. 121 | 122 | a. Adapted Material means material subject to Copyright and Similar 123 | Rights that is derived from or based upon the Licensed Material 124 | and in which the Licensed Material is translated, altered, 125 | arranged, transformed, or otherwise modified in a manner requiring 126 | permission under the Copyright and Similar Rights held by the 127 | Licensor. For purposes of this Public License, where the Licensed 128 | Material is a musical work, performance, or sound recording, 129 | Adapted Material is always produced where the Licensed Material is 130 | synched in timed relation with a moving image. 131 | 132 | b. Adapter's License means the license You apply to Your Copyright 133 | and Similar Rights in Your contributions to Adapted Material in 134 | accordance with the terms and conditions of this Public License. 135 | 136 | c. Copyright and Similar Rights means copyright and/or similar rights 137 | closely related to copyright including, without limitation, 138 | performance, broadcast, sound recording, and Sui Generis Database 139 | Rights, without regard to how the rights are labeled or 140 | categorized. For purposes of this Public License, the rights 141 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 142 | Rights. 143 | 144 | d. Effective Technological Measures means those measures that, in the 145 | absence of proper authority, may not be circumvented under laws 146 | fulfilling obligations under Article 11 of the WIPO Copyright 147 | Treaty adopted on December 20, 1996, and/or similar international 148 | agreements. 149 | 150 | e. Exceptions and Limitations means fair use, fair dealing, and/or 151 | any other exception or limitation to Copyright and Similar Rights 152 | that applies to Your use of the Licensed Material. 153 | 154 | f. Licensed Material means the artistic or literary work, database, 155 | or other material to which the Licensor applied this Public 156 | License. 157 | 158 | g. Licensed Rights means the rights granted to You subject to the 159 | terms and conditions of this Public License, which are limited to 160 | all Copyright and Similar Rights that apply to Your use of the 161 | Licensed Material and that the Licensor has authority to license. 162 | 163 | h. Licensor means the individual(s) or entity(ies) granting rights 164 | under this Public License. 165 | 166 | i. Share means to provide material to the public by any means or 167 | process that requires permission under the Licensed Rights, such 168 | as reproduction, public display, public performance, distribution, 169 | dissemination, communication, or importation, and to make material 170 | available to the public including in ways that members of the 171 | public may access the material from a place and at a time 172 | individually chosen by them. 173 | 174 | j. Sui Generis Database Rights means rights other than copyright 175 | resulting from Directive 96/9/EC of the European Parliament and of 176 | the Council of 11 March 1996 on the legal protection of databases, 177 | as amended and/or succeeded, as well as other essentially 178 | equivalent rights anywhere in the world. 179 | 180 | k. You means the individual or entity exercising the Licensed Rights 181 | under this Public License. Your has a corresponding meaning. 182 | 183 | 184 | Section 2 -- Scope. 185 | 186 | a. License grant. 187 | 188 | 1. Subject to the terms and conditions of this Public License, 189 | the Licensor hereby grants You a worldwide, royalty-free, 190 | non-sublicensable, non-exclusive, irrevocable license to 191 | exercise the Licensed Rights in the Licensed Material to: 192 | 193 | a. reproduce and Share the Licensed Material, in whole or 194 | in part; and 195 | 196 | b. produce, reproduce, and Share Adapted Material. 197 | 198 | 2. Exceptions and Limitations. For the avoidance of doubt, where 199 | Exceptions and Limitations apply to Your use, this Public 200 | License does not apply, and You do not need to comply with 201 | its terms and conditions. 202 | 203 | 3. Term. The term of this Public License is specified in Section 204 | 6(a). 205 | 206 | 4. Media and formats; technical modifications allowed. The 207 | Licensor authorizes You to exercise the Licensed Rights in 208 | all media and formats whether now known or hereafter created, 209 | and to make technical modifications necessary to do so. The 210 | Licensor waives and/or agrees not to assert any right or 211 | authority to forbid You from making technical modifications 212 | necessary to exercise the Licensed Rights, including 213 | technical modifications necessary to circumvent Effective 214 | Technological Measures. For purposes of this Public License, 215 | simply making modifications authorized by this Section 2(a) 216 | (4) never produces Adapted Material. 217 | 218 | 5. Downstream recipients. 219 | 220 | a. Offer from the Licensor -- Licensed Material. Every 221 | recipient of the Licensed Material automatically 222 | receives an offer from the Licensor to exercise the 223 | Licensed Rights under the terms and conditions of this 224 | Public License. 225 | 226 | b. No downstream restrictions. You may not offer or impose 227 | any additional or different terms or conditions on, or 228 | apply any Effective Technological Measures to, the 229 | Licensed Material if doing so restricts exercise of the 230 | Licensed Rights by any recipient of the Licensed 231 | Material. 232 | 233 | 6. No endorsement. Nothing in this Public License constitutes or 234 | may be construed as permission to assert or imply that You 235 | are, or that Your use of the Licensed Material is, connected 236 | with, or sponsored, endorsed, or granted official status by, 237 | the Licensor or others designated to receive attribution as 238 | provided in Section 3(a)(1)(A)(i). 239 | 240 | b. Other rights. 241 | 242 | 1. Moral rights, such as the right of integrity, are not 243 | licensed under this Public License, nor are publicity, 244 | privacy, and/or other similar personality rights; however, to 245 | the extent possible, the Licensor waives and/or agrees not to 246 | assert any such rights held by the Licensor to the limited 247 | extent necessary to allow You to exercise the Licensed 248 | Rights, but not otherwise. 249 | 250 | 2. Patent and trademark rights are not licensed under this 251 | Public License. 252 | 253 | 3. To the extent possible, the Licensor waives any right to 254 | collect royalties from You for the exercise of the Licensed 255 | Rights, whether directly or through a collecting society 256 | under any voluntary or waivable statutory or compulsory 257 | licensing scheme. In all other cases the Licensor expressly 258 | reserves any right to collect such royalties. 259 | 260 | 261 | Section 3 -- License Conditions. 262 | 263 | Your exercise of the Licensed Rights is expressly made subject to the 264 | following conditions. 265 | 266 | a. Attribution. 267 | 268 | 1. If You Share the Licensed Material (including in modified 269 | form), You must: 270 | 271 | a. retain the following if it is supplied by the Licensor 272 | with the Licensed Material: 273 | 274 | i. identification of the creator(s) of the Licensed 275 | Material and any others designated to receive 276 | attribution, in any reasonable manner requested by 277 | the Licensor (including by pseudonym if 278 | designated); 279 | 280 | ii. a copyright notice; 281 | 282 | iii. a notice that refers to this Public License; 283 | 284 | iv. a notice that refers to the disclaimer of 285 | warranties; 286 | 287 | v. a URI or hyperlink to the Licensed Material to the 288 | extent reasonably practicable; 289 | 290 | b. indicate if You modified the Licensed Material and 291 | retain an indication of any previous modifications; and 292 | 293 | c. indicate the Licensed Material is licensed under this 294 | Public License, and include the text of, or the URI or 295 | hyperlink to, this Public License. 296 | 297 | 2. You may satisfy the conditions in Section 3(a)(1) in any 298 | reasonable manner based on the medium, means, and context in 299 | which You Share the Licensed Material. For example, it may be 300 | reasonable to satisfy the conditions by providing a URI or 301 | hyperlink to a resource that includes the required 302 | information. 303 | 304 | 3. If requested by the Licensor, You must remove any of the 305 | information required by Section 3(a)(1)(A) to the extent 306 | reasonably practicable. 307 | 308 | 4. If You Share Adapted Material You produce, the Adapter's 309 | License You apply must not prevent recipients of the Adapted 310 | Material from complying with this Public License. 311 | 312 | 313 | Section 4 -- Sui Generis Database Rights. 314 | 315 | Where the Licensed Rights include Sui Generis Database Rights that 316 | apply to Your use of the Licensed Material: 317 | 318 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 319 | to extract, reuse, reproduce, and Share all or a substantial 320 | portion of the contents of the database; 321 | 322 | b. if You include all or a substantial portion of the database 323 | contents in a database in which You have Sui Generis Database 324 | Rights, then the database in which You have Sui Generis Database 325 | Rights (but not its individual contents) is Adapted Material; and 326 | 327 | c. You must comply with the conditions in Section 3(a) if You Share 328 | all or a substantial portion of the contents of the database. 329 | 330 | For the avoidance of doubt, this Section 4 supplements and does not 331 | replace Your obligations under this Public License where the Licensed 332 | Rights include other Copyright and Similar Rights. 333 | 334 | 335 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 336 | 337 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 338 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 339 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 340 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 341 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 342 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 343 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 344 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 345 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 346 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 347 | 348 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 349 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 350 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 351 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 352 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 353 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 354 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 355 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 356 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 357 | 358 | c. The disclaimer of warranties and limitation of liability provided 359 | above shall be interpreted in a manner that, to the extent 360 | possible, most closely approximates an absolute disclaimer and 361 | waiver of all liability. 362 | 363 | 364 | Section 6 -- Term and Termination. 365 | 366 | a. This Public License applies for the term of the Copyright and 367 | Similar Rights licensed here. However, if You fail to comply with 368 | this Public License, then Your rights under this Public License 369 | terminate automatically. 370 | 371 | b. Where Your right to use the Licensed Material has terminated under 372 | Section 6(a), it reinstates: 373 | 374 | 1. automatically as of the date the violation is cured, provided 375 | it is cured within 30 days of Your discovery of the 376 | violation; or 377 | 378 | 2. upon express reinstatement by the Licensor. 379 | 380 | For the avoidance of doubt, this Section 6(b) does not affect any 381 | right the Licensor may have to seek remedies for Your violations 382 | of this Public License. 383 | 384 | c. For the avoidance of doubt, the Licensor may also offer the 385 | Licensed Material under separate terms or conditions or stop 386 | distributing the Licensed Material at any time; however, doing so 387 | will not terminate this Public License. 388 | 389 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 390 | License. 391 | 392 | 393 | Section 7 -- Other Terms and Conditions. 394 | 395 | a. The Licensor shall not be bound by any additional or different 396 | terms or conditions communicated by You unless expressly agreed. 397 | 398 | b. Any arrangements, understandings, or agreements regarding the 399 | Licensed Material not stated herein are separate from and 400 | independent of the terms and conditions of this Public License. 401 | 402 | 403 | Section 8 -- Interpretation. 404 | 405 | a. For the avoidance of doubt, this Public License does not, and 406 | shall not be interpreted to, reduce, limit, restrict, or impose 407 | conditions on any use of the Licensed Material that could lawfully 408 | be made without permission under this Public License. 409 | 410 | b. To the extent possible, if any provision of this Public License is 411 | deemed unenforceable, it shall be automatically reformed to the 412 | minimum extent necessary to make it enforceable. If the provision 413 | cannot be reformed, it shall be severed from this Public License 414 | without affecting the enforceability of the remaining terms and 415 | conditions. 416 | 417 | c. No term or condition of this Public License will be waived and no 418 | failure to comply consented to unless expressly agreed to by the 419 | Licensor. 420 | 421 | d. Nothing in this Public License constitutes or may be interpreted 422 | as a limitation upon, or waiver of, any privileges and immunities 423 | that apply to the Licensor or You, including from the legal 424 | processes of any jurisdiction or authority. 425 | 426 | 427 | ======================================================================= 428 | 429 | Creative Commons is not a party to its public 430 | licenses. Notwithstanding, Creative Commons may elect to apply one of 431 | its public licenses to material it publishes and in those instances 432 | will be considered the “Licensor.” The text of the Creative Commons 433 | public licenses is dedicated to the public domain under the CC0 Public 434 | Domain Dedication. Except for the limited purpose of indicating that 435 | material is shared under a Creative Commons public license or as 436 | otherwise permitted by the Creative Commons policies published at 437 | creativecommons.org/policies, Creative Commons does not authorize the 438 | use of the trademark "Creative Commons" or any other trademark or logo 439 | of Creative Commons without its prior written consent including, 440 | without limitation, in connection with any unauthorized modifications 441 | to any of its public licenses or any other arrangements, 442 | understandings, or agreements concerning use of licensed material. For 443 | the avoidance of doubt, this paragraph does not form part of the 444 | public licenses. 445 | 446 | Creative Commons may be contacted at creativecommons.org. 447 | {% elif cookiecutter.open_source_license == 'Apache Software License 2.0' -%}Apache Software License 2.0 448 | 449 | Copyright (c) {% now 'local', '%Y' %}, {{ cookiecutter.author_name }} 450 | 451 | Licensed under the Apache License, Version 2.0 (the "License"); 452 | you may not use this file except in compliance with the License. 453 | You may obtain a copy of the License at 454 | 455 | http://www.apache.org/licenses/LICENSE-2.0 456 | 457 | Unless required by applicable law or agreed to in writing, software 458 | distributed under the License is distributed on an "AS IS" BASIS, 459 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 460 | See the License for the specific language governing permissions and 461 | limitations under the License. 462 | {% elif cookiecutter.open_source_license == 'CC BY-SA 4.0' -%}Attribution-ShareAlike 4.0 International 463 | 464 | ======================================================================= 465 | 466 | Creative Commons Corporation ("Creative Commons") is not a law firm and 467 | does not provide legal services or legal advice. Distribution of 468 | Creative Commons public licenses does not create a lawyer-client or 469 | other relationship. Creative Commons makes its licenses and related 470 | information available on an "as-is" basis. Creative Commons gives no 471 | warranties regarding its licenses, any material licensed under their 472 | terms and conditions, or any related information. Creative Commons 473 | disclaims all liability for damages resulting from their use to the 474 | fullest extent possible. 475 | 476 | Using Creative Commons Public Licenses 477 | 478 | Creative Commons public licenses provide a standard set of terms and 479 | conditions that creators and other rights holders may use to share 480 | original works of authorship and other material subject to copyright 481 | and certain other rights specified in the public license below. The 482 | following considerations are for informational purposes only, are not 483 | exhaustive, and do not form part of our licenses. 484 | 485 | Considerations for licensors: Our public licenses are 486 | intended for use by those authorized to give the public 487 | permission to use material in ways otherwise restricted by 488 | copyright and certain other rights. Our licenses are 489 | irrevocable. Licensors should read and understand the terms 490 | and conditions of the license they choose before applying it. 491 | Licensors should also secure all rights necessary before 492 | applying our licenses so that the public can reuse the 493 | material as expected. Licensors should clearly mark any 494 | material not subject to the license. This includes other CC- 495 | licensed material, or material used under an exception or 496 | limitation to copyright. More considerations for licensors: 497 | wiki.creativecommons.org/Considerations_for_licensors 498 | 499 | Considerations for the public: By using one of our public 500 | licenses, a licensor grants the public permission to use the 501 | licensed material under specified terms and conditions. If 502 | the licensor's permission is not necessary for any reason--for 503 | example, because of any applicable exception or limitation to 504 | copyright--then that use is not regulated by the license. Our 505 | licenses grant only permissions under copyright and certain 506 | other rights that a licensor has authority to grant. Use of 507 | the licensed material may still be restricted for other 508 | reasons, including because others have copyright or other 509 | rights in the material. A licensor may make special requests, 510 | such as asking that all changes be marked or described. 511 | Although not required by our licenses, you are encouraged to 512 | respect those requests where reasonable. More considerations 513 | for the public: 514 | wiki.creativecommons.org/Considerations_for_licensees 515 | 516 | ======================================================================= 517 | 518 | Creative Commons Attribution-ShareAlike 4.0 International Public 519 | License 520 | 521 | By exercising the Licensed Rights (defined below), You accept and agree 522 | to be bound by the terms and conditions of this Creative Commons 523 | Attribution-ShareAlike 4.0 International Public License ("Public 524 | License"). To the extent this Public License may be interpreted as a 525 | contract, You are granted the Licensed Rights in consideration of Your 526 | acceptance of these terms and conditions, and the Licensor grants You 527 | such rights in consideration of benefits the Licensor receives from 528 | making the Licensed Material available under these terms and 529 | conditions. 530 | 531 | 532 | Section 1 -- Definitions. 533 | 534 | a. Adapted Material means material subject to Copyright and Similar 535 | Rights that is derived from or based upon the Licensed Material 536 | and in which the Licensed Material is translated, altered, 537 | arranged, transformed, or otherwise modified in a manner requiring 538 | permission under the Copyright and Similar Rights held by the 539 | Licensor. For purposes of this Public License, where the Licensed 540 | Material is a musical work, performance, or sound recording, 541 | Adapted Material is always produced where the Licensed Material is 542 | synched in timed relation with a moving image. 543 | 544 | b. Adapter's License means the license You apply to Your Copyright 545 | and Similar Rights in Your contributions to Adapted Material in 546 | accordance with the terms and conditions of this Public License. 547 | 548 | c. BY-SA Compatible License means a license listed at 549 | creativecommons.org/compatiblelicenses, approved by Creative 550 | Commons as essentially the equivalent of this Public License. 551 | 552 | d. Copyright and Similar Rights means copyright and/or similar rights 553 | closely related to copyright including, without limitation, 554 | performance, broadcast, sound recording, and Sui Generis Database 555 | Rights, without regard to how the rights are labeled or 556 | categorized. For purposes of this Public License, the rights 557 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 558 | Rights. 559 | 560 | e. Effective Technological Measures means those measures that, in the 561 | absence of proper authority, may not be circumvented under laws 562 | fulfilling obligations under Article 11 of the WIPO Copyright 563 | Treaty adopted on December 20, 1996, and/or similar international 564 | agreements. 565 | 566 | f. Exceptions and Limitations means fair use, fair dealing, and/or 567 | any other exception or limitation to Copyright and Similar Rights 568 | that applies to Your use of the Licensed Material. 569 | 570 | g. License Elements means the license attributes listed in the name 571 | of a Creative Commons Public License. The License Elements of this 572 | Public License are Attribution and ShareAlike. 573 | 574 | h. Licensed Material means the artistic or literary work, database, 575 | or other material to which the Licensor applied this Public 576 | License. 577 | 578 | i. Licensed Rights means the rights granted to You subject to the 579 | terms and conditions of this Public License, which are limited to 580 | all Copyright and Similar Rights that apply to Your use of the 581 | Licensed Material and that the Licensor has authority to license. 582 | 583 | j. Licensor means the individual(s) or entity(ies) granting rights 584 | under this Public License. 585 | 586 | k. Share means to provide material to the public by any means or 587 | process that requires permission under the Licensed Rights, such 588 | as reproduction, public display, public performance, distribution, 589 | dissemination, communication, or importation, and to make material 590 | available to the public including in ways that members of the 591 | public may access the material from a place and at a time 592 | individually chosen by them. 593 | 594 | l. Sui Generis Database Rights means rights other than copyright 595 | resulting from Directive 96/9/EC of the European Parliament and of 596 | the Council of 11 March 1996 on the legal protection of databases, 597 | as amended and/or succeeded, as well as other essentially 598 | equivalent rights anywhere in the world. 599 | 600 | m. You means the individual or entity exercising the Licensed Rights 601 | under this Public License. Your has a corresponding meaning. 602 | 603 | 604 | Section 2 -- Scope. 605 | 606 | a. License grant. 607 | 608 | 1. Subject to the terms and conditions of this Public License, 609 | the Licensor hereby grants You a worldwide, royalty-free, 610 | non-sublicensable, non-exclusive, irrevocable license to 611 | exercise the Licensed Rights in the Licensed Material to: 612 | 613 | a. reproduce and Share the Licensed Material, in whole or 614 | in part; and 615 | 616 | b. produce, reproduce, and Share Adapted Material. 617 | 618 | 2. Exceptions and Limitations. For the avoidance of doubt, where 619 | Exceptions and Limitations apply to Your use, this Public 620 | License does not apply, and You do not need to comply with 621 | its terms and conditions. 622 | 623 | 3. Term. The term of this Public License is specified in Section 624 | 6(a). 625 | 626 | 4. Media and formats; technical modifications allowed. The 627 | Licensor authorizes You to exercise the Licensed Rights in 628 | all media and formats whether now known or hereafter created, 629 | and to make technical modifications necessary to do so. The 630 | Licensor waives and/or agrees not to assert any right or 631 | authority to forbid You from making technical modifications 632 | necessary to exercise the Licensed Rights, including 633 | technical modifications necessary to circumvent Effective 634 | Technological Measures. For purposes of this Public License, 635 | simply making modifications authorized by this Section 2(a) 636 | (4) never produces Adapted Material. 637 | 638 | 5. Downstream recipients. 639 | 640 | a. Offer from the Licensor -- Licensed Material. Every 641 | recipient of the Licensed Material automatically 642 | receives an offer from the Licensor to exercise the 643 | Licensed Rights under the terms and conditions of this 644 | Public License. 645 | 646 | b. Additional offer from the Licensor -- Adapted Material. 647 | Every recipient of Adapted Material from You 648 | automatically receives an offer from the Licensor to 649 | exercise the Licensed Rights in the Adapted Material 650 | under the conditions of the Adapter's License You apply. 651 | 652 | c. No downstream restrictions. You may not offer or impose 653 | any additional or different terms or conditions on, or 654 | apply any Effective Technological Measures to, the 655 | Licensed Material if doing so restricts exercise of the 656 | Licensed Rights by any recipient of the Licensed 657 | Material. 658 | 659 | 6. No endorsement. Nothing in this Public License constitutes or 660 | may be construed as permission to assert or imply that You 661 | are, or that Your use of the Licensed Material is, connected 662 | with, or sponsored, endorsed, or granted official status by, 663 | the Licensor or others designated to receive attribution as 664 | provided in Section 3(a)(1)(A)(i). 665 | 666 | b. Other rights. 667 | 668 | 1. Moral rights, such as the right of integrity, are not 669 | licensed under this Public License, nor are publicity, 670 | privacy, and/or other similar personality rights; however, to 671 | the extent possible, the Licensor waives and/or agrees not to 672 | assert any such rights held by the Licensor to the limited 673 | extent necessary to allow You to exercise the Licensed 674 | Rights, but not otherwise. 675 | 676 | 2. Patent and trademark rights are not licensed under this 677 | Public License. 678 | 679 | 3. To the extent possible, the Licensor waives any right to 680 | collect royalties from You for the exercise of the Licensed 681 | Rights, whether directly or through a collecting society 682 | under any voluntary or waivable statutory or compulsory 683 | licensing scheme. In all other cases the Licensor expressly 684 | reserves any right to collect such royalties. 685 | 686 | 687 | Section 3 -- License Conditions. 688 | 689 | Your exercise of the Licensed Rights is expressly made subject to the 690 | following conditions. 691 | 692 | a. Attribution. 693 | 694 | 1. If You Share the Licensed Material (including in modified 695 | form), You must: 696 | 697 | a. retain the following if it is supplied by the Licensor 698 | with the Licensed Material: 699 | 700 | i. identification of the creator(s) of the Licensed 701 | Material and any others designated to receive 702 | attribution, in any reasonable manner requested by 703 | the Licensor (including by pseudonym if 704 | designated); 705 | 706 | ii. a copyright notice; 707 | 708 | iii. a notice that refers to this Public License; 709 | 710 | iv. a notice that refers to the disclaimer of 711 | warranties; 712 | 713 | v. a URI or hyperlink to the Licensed Material to the 714 | extent reasonably practicable; 715 | 716 | b. indicate if You modified the Licensed Material and 717 | retain an indication of any previous modifications; and 718 | 719 | c. indicate the Licensed Material is licensed under this 720 | Public License, and include the text of, or the URI or 721 | hyperlink to, this Public License. 722 | 723 | 2. You may satisfy the conditions in Section 3(a)(1) in any 724 | reasonable manner based on the medium, means, and context in 725 | which You Share the Licensed Material. For example, it may be 726 | reasonable to satisfy the conditions by providing a URI or 727 | hyperlink to a resource that includes the required 728 | information. 729 | 730 | 3. If requested by the Licensor, You must remove any of the 731 | information required by Section 3(a)(1)(A) to the extent 732 | reasonably practicable. 733 | 734 | b. ShareAlike. 735 | 736 | In addition to the conditions in Section 3(a), if You Share 737 | Adapted Material You produce, the following conditions also apply. 738 | 739 | 1. The Adapter's License You apply must be a Creative Commons 740 | license with the same License Elements, this version or 741 | later, or a BY-SA Compatible License. 742 | 743 | 2. You must include the text of, or the URI or hyperlink to, the 744 | Adapter's License You apply. You may satisfy this condition 745 | in any reasonable manner based on the medium, means, and 746 | context in which You Share Adapted Material. 747 | 748 | 3. You may not offer or impose any additional or different terms 749 | or conditions on, or apply any Effective Technological 750 | Measures to, Adapted Material that restrict exercise of the 751 | rights granted under the Adapter's License You apply. 752 | 753 | 754 | Section 4 -- Sui Generis Database Rights. 755 | 756 | Where the Licensed Rights include Sui Generis Database Rights that 757 | apply to Your use of the Licensed Material: 758 | 759 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 760 | to extract, reuse, reproduce, and Share all or a substantial 761 | portion of the contents of the database; 762 | 763 | b. if You include all or a substantial portion of the database 764 | contents in a database in which You have Sui Generis Database 765 | Rights, then the database in which You have Sui Generis Database 766 | Rights (but not its individual contents) is Adapted Material, 767 | including for purposes of Section 3(b); and 768 | 769 | c. You must comply with the conditions in Section 3(a) if You Share 770 | all or a substantial portion of the contents of the database. 771 | 772 | For the avoidance of doubt, this Section 4 supplements and does not 773 | replace Your obligations under this Public License where the Licensed 774 | Rights include other Copyright and Similar Rights. 775 | 776 | 777 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 778 | 779 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 780 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 781 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 782 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 783 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 784 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 785 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 786 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 787 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 788 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 789 | 790 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 791 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 792 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 793 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 794 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 795 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 796 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 797 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 798 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 799 | 800 | c. The disclaimer of warranties and limitation of liability provided 801 | above shall be interpreted in a manner that, to the extent 802 | possible, most closely approximates an absolute disclaimer and 803 | waiver of all liability. 804 | 805 | 806 | Section 6 -- Term and Termination. 807 | 808 | a. This Public License applies for the term of the Copyright and 809 | Similar Rights licensed here. However, if You fail to comply with 810 | this Public License, then Your rights under this Public License 811 | terminate automatically. 812 | 813 | b. Where Your right to use the Licensed Material has terminated under 814 | Section 6(a), it reinstates: 815 | 816 | 1. automatically as of the date the violation is cured, provided 817 | it is cured within 30 days of Your discovery of the 818 | violation; or 819 | 820 | 2. upon express reinstatement by the Licensor. 821 | 822 | For the avoidance of doubt, this Section 6(b) does not affect any 823 | right the Licensor may have to seek remedies for Your violations 824 | of this Public License. 825 | 826 | c. For the avoidance of doubt, the Licensor may also offer the 827 | Licensed Material under separate terms or conditions or stop 828 | distributing the Licensed Material at any time; however, doing so 829 | will not terminate this Public License. 830 | 831 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 832 | License. 833 | 834 | 835 | Section 7 -- Other Terms and Conditions. 836 | 837 | a. The Licensor shall not be bound by any additional or different 838 | terms or conditions communicated by You unless expressly agreed. 839 | 840 | b. Any arrangements, understandings, or agreements regarding the 841 | Licensed Material not stated herein are separate from and 842 | independent of the terms and conditions of this Public License. 843 | 844 | 845 | Section 8 -- Interpretation. 846 | 847 | a. For the avoidance of doubt, this Public License does not, and 848 | shall not be interpreted to, reduce, limit, restrict, or impose 849 | conditions on any use of the Licensed Material that could lawfully 850 | be made without permission under this Public License. 851 | 852 | b. To the extent possible, if any provision of this Public License is 853 | deemed unenforceable, it shall be automatically reformed to the 854 | minimum extent necessary to make it enforceable. If the provision 855 | cannot be reformed, it shall be severed from this Public License 856 | without affecting the enforceability of the remaining terms and 857 | conditions. 858 | 859 | c. No term or condition of this Public License will be waived and no 860 | failure to comply consented to unless expressly agreed to by the 861 | Licensor. 862 | 863 | d. Nothing in this Public License constitutes or may be interpreted 864 | as a limitation upon, or waiver of, any privileges and immunities 865 | that apply to the Licensor or You, including from the legal 866 | processes of any jurisdiction or authority. 867 | 868 | 869 | ======================================================================= 870 | 871 | Creative Commons is not a party to its public 872 | licenses. Notwithstanding, Creative Commons may elect to apply one of 873 | its public licenses to material it publishes and in those instances 874 | will be considered the “Licensor.” The text of the Creative Commons 875 | public licenses is dedicated to the public domain under the CC0 Public 876 | Domain Dedication. Except for the limited purpose of indicating that 877 | material is shared under a Creative Commons public license or as 878 | otherwise permitted by the Creative Commons policies published at 879 | creativecommons.org/policies, Creative Commons does not authorize the 880 | use of the trademark "Creative Commons" or any other trademark or logo 881 | of Creative Commons without its prior written consent including, 882 | without limitation, in connection with any unauthorized modifications 883 | to any of its public licenses or any other arrangements, 884 | understandings, or agreements concerning use of licensed material. For 885 | the avoidance of doubt, this paragraph does not form part of the 886 | public licenses. 887 | 888 | Creative Commons may be contacted at creativecommons.org. 889 | {% endif %} -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/README.md: -------------------------------------------------------------------------------- 1 | # {{ cookiecutter.book_name }} 2 | 3 | {{ cookiecutter.book_short_description }} 4 | 5 | ## Usage 6 | 7 | ### Building the book 8 | 9 | If you'd like to develop and/or build the {{ cookiecutter.book_name }} book, you should: 10 | 11 | 1. Clone this repository 12 | 2. Run `pip install -r requirements.txt` (it is recommended you do this within a virtual environment) 13 | 3. (Optional) Edit the books source files located in the `{{ cookiecutter.book_slug }}/` directory 14 | 4. Run `jupyter-book clean {{ cookiecutter.book_slug }}/` to remove any existing builds 15 | 5. Run `jupyter-book build {{ cookiecutter.book_slug }}/` 16 | 17 | A fully-rendered HTML version of the book will be built in `{{ cookiecutter.book_slug }}/_build/html/`. 18 | 19 | ### Hosting the book 20 | 21 | Please see the [Jupyter Book documentation](https://jupyterbook.org/publish/web.html) to discover options for deploying a book online using services such as GitHub, GitLab, or Netlify. 22 | 23 | For GitHub and GitLab deployment specifically, the [cookiecutter-jupyter-book](https://github.com/executablebooks/cookiecutter-jupyter-book) includes templates for, and information about, optional continuous integration (CI) workflow files to help easily and automatically deploy books online with GitHub or GitLab. For example, if you chose `github` for the `include_ci` cookiecutter option, your book template was created with a GitHub actions workflow file that, once pushed to GitHub, automatically renders and pushes your book to the `gh-pages` branch of your repo and hosts it on GitHub Pages when a push or pull request is made to the main branch. 24 | 25 | ## Contributors 26 | 27 | We welcome and recognize all contributions. You can see a list of current contributors in the [contributors tab](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.book_slug }}/graphs/contributors). 28 | 29 | ## Credits 30 | 31 | This project is created using the excellent open source [Jupyter Book project](https://jupyterbook.org/) and the [executablebooks/cookiecutter-jupyter-book template](https://github.com/executablebooks/cookiecutter-jupyter-book). 32 | -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/requirements.txt: -------------------------------------------------------------------------------- 1 | jupyter-book 2 | matplotlib 3 | numpy 4 | {% if cookiecutter.include_ci == 'github' -%}ghp-import{% endif %} -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/_config.yml: -------------------------------------------------------------------------------- 1 | ####################################################################################### 2 | # A default configuration that will be loaded for all jupyter books 3 | # See the documentation for help and more options: 4 | # https://jupyterbook.org/customize/config.html 5 | 6 | ####################################################################################### 7 | # Book settings 8 | title : {{ cookiecutter.book_name }} # The title of the book. Will be placed in the left navbar. 9 | author : {{ cookiecutter.author_name }} # The author of the book 10 | copyright : "{% now 'local', '%Y' %}" # Copyright year to be placed in the footer 11 | logo : logo.png # A path to the book logo 12 | 13 | # Force re-execution of notebooks on each build. 14 | # See https://jupyterbook.org/content/execute.html 15 | execute: 16 | execute_notebooks: force 17 | 18 | # Define the name of the latex output file for PDF builds 19 | latex: 20 | latex_documents: 21 | targetname: book.tex 22 | 23 | # Add a bibtex file so that we can create citations 24 | bibtex_bibfiles: 25 | - references.bib 26 | 27 | # Information about where the book exists on the web 28 | repository: 29 | url: https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.book_name }} # Online location of your book 30 | path_to_book: docs # Optional path to your book, relative to the repository root 31 | branch: main # Which branch of the repository should be used when creating links (optional) 32 | 33 | # Add GitHub buttons to your book 34 | # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository 35 | html: 36 | use_issues_button: true 37 | use_repository_button: true -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/_toc-legacy.yml: -------------------------------------------------------------------------------- 1 | # Table of content 2 | # Learn more at https://jupyterbook.org/customize/toc.html 3 | # 4 | - file: intro 5 | - file: content 6 | sections: 7 | - file: markdown 8 | - file: notebooks 9 | - file: markdown-notebooks 10 | -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/_toc.yml: -------------------------------------------------------------------------------- 1 | # Table of contents 2 | # Learn more at https://jupyterbook.org/customize/toc.html 3 | 4 | format: jb-book 5 | root: intro 6 | chapters: 7 | - file: markdown 8 | - file: notebooks 9 | - file: markdown-notebooks -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/content.md: -------------------------------------------------------------------------------- 1 | Content in Jupyter Book 2 | ======================= 3 | 4 | There are many ways to write content in Jupyter Book. This short section 5 | covers a few tips for how to do so. 6 | -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/intro.md: -------------------------------------------------------------------------------- 1 | # Welcome to your Jupyter Book 2 | 3 | This is a small sample book to give you a feel for how book content is 4 | structured. 5 | It shows off a few of the major file types, as well as some sample content. 6 | It does not go in-depth into any particular topic - check out [the Jupyter Book documentation](https://jupyterbook.org) for more information. 7 | 8 | Check out the content pages bundled with this sample book to see more. 9 | 10 | ```{tableofcontents} 11 | ``` -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/executablebooks/cookiecutter-jupyter-book/1c03d6735aba5bc34c429739bd3c81535f945f45/{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/logo.png -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/markdown-notebooks.md: -------------------------------------------------------------------------------- 1 | --- 2 | jupytext: 3 | cell_metadata_filter: -all 4 | formats: md:myst 5 | text_representation: 6 | extension: .md 7 | format_name: myst 8 | format_version: 0.13 9 | jupytext_version: 1.11.5 10 | kernelspec: 11 | display_name: Python 3 12 | language: python 13 | name: python3 14 | --- 15 | 16 | # Notebooks with MyST Markdown 17 | 18 | Jupyter Book also lets you write text-based notebooks using MyST Markdown. 19 | See [the Notebooks with MyST Markdown documentation](https://jupyterbook.org/file-types/myst-notebooks.html) for more detailed instructions. 20 | This page shows off a notebook written in MyST Markdown. 21 | 22 | ## An example cell 23 | 24 | With MyST Markdown, you can define code cells with a directive like so: 25 | 26 | ```{code-cell} 27 | print(2 + 2) 28 | ``` 29 | 30 | When your book is built, the contents of any `{code-cell}` blocks will be 31 | executed with your default Jupyter kernel, and their outputs will be displayed 32 | in-line with the rest of your content. 33 | 34 | ```{seealso} 35 | Jupyter Book uses [Jupytext](https://jupytext.readthedocs.io/en/latest/) to convert text-based files to notebooks, and can support [many other text-based notebook files](https://jupyterbook.org/file-types/jupytext.html). 36 | ``` 37 | 38 | ## Create a notebook with MyST Markdown 39 | 40 | MyST Markdown notebooks are defined by two things: 41 | 42 | 1. YAML metadata that is needed to understand if / how it should convert text files to notebooks (including information about the kernel needed). 43 | See the YAML at the top of this page for example. 44 | 2. The presence of `{code-cell}` directives, which will be executed with your book. 45 | 46 | That's all that is needed to get started! 47 | 48 | ## Quickly add YAML metadata for MyST Notebooks 49 | 50 | If you have a markdown file and you'd like to quickly add YAML metadata to it, so that Jupyter Book will treat it as a MyST Markdown Notebook, run the following command: 51 | 52 | ``` 53 | jupyter-book myst init path/to/markdownfile.md 54 | ``` -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/markdown.md: -------------------------------------------------------------------------------- 1 | # Markdown Files 2 | 3 | Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or 4 | in regular markdown files (`.md`), you'll write in the same flavor of markdown 5 | called **MyST Markdown**. 6 | This is a simple file to help you get started and show off some syntax. 7 | 8 | ## What is MyST? 9 | 10 | MyST stands for "Markedly Structured Text". It 11 | is a slight variation on a flavor of markdown called "CommonMark" markdown, 12 | with small syntax extensions to allow you to write **roles** and **directives** 13 | in the Sphinx ecosystem. 14 | 15 | For more about MyST, see [the MyST Markdown Overview](https://jupyterbook.org/content/myst.html). 16 | 17 | ## Sample Roles and Directives 18 | 19 | Roles and directives are two of the most powerful tools in Jupyter Book. They 20 | are kind of like functions, but written in a markup language. They both 21 | serve a similar purpose, but **roles are written in one line**, whereas 22 | **directives span many lines**. They both accept different kinds of inputs, 23 | and what they do with those inputs depends on the specific role or directive 24 | that is being called. 25 | 26 | Here is a "note" directive: 27 | 28 | ```{note} 29 | Here is a note 30 | ``` 31 | 32 | It will be rendered in a special box when you build your book. 33 | 34 | Here is an inline directive to refer to a document: {doc}`markdown-notebooks`. 35 | 36 | 37 | ## Citations 38 | 39 | You can also cite references that are stored in a `bibtex` file. For example, 40 | the following syntax: `` {cite}`holdgraf_evidence_2014` `` will render like 41 | this: {cite}`holdgraf_evidence_2014`. 42 | 43 | Moreover, you can insert a bibliography into your page with this syntax: 44 | The `{bibliography}` directive must be used for all the `{cite}` roles to 45 | render properly. 46 | For example, if the references for your book are stored in `references.bib`, 47 | then the bibliography is inserted with: 48 | 49 | ```{bibliography} 50 | ``` 51 | 52 | ## Learn more 53 | 54 | This is just a simple starter to get you started. 55 | You can learn a lot more at [jupyterbook.org](https://jupyterbook.org). -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/notebooks.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": {}, 6 | "source": [ 7 | "# Content with notebooks\n", 8 | "\n", 9 | "You can also create content with Jupyter Notebooks. This means that you can include\n", 10 | "code blocks and their outputs in your book.\n", 11 | "\n", 12 | "## Markdown + notebooks\n", 13 | "\n", 14 | "As it is markdown, you can embed images, HTML, etc into your posts!\n", 15 | "\n", 16 | "![](https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg)\n", 17 | "\n", 18 | "You can also $add_{math}$ and\n", 19 | "\n", 20 | "$$\n", 21 | "math^{blocks}\n", 22 | "$$\n", 23 | "\n", 24 | "or\n", 25 | "\n", 26 | "$$\n", 27 | "\\begin{aligned}\n", 28 | "\\mbox{mean} la_{tex} \\\\ \\\\\n", 29 | "math blocks\n", 30 | "\\end{aligned}\n", 31 | "$$\n", 32 | "\n", 33 | "But make sure you \\$Escape \\$your \\$dollar signs \\$you want to keep!\n", 34 | "\n", 35 | "## MyST markdown\n", 36 | "\n", 37 | "MyST markdown works in Jupyter Notebooks as well. For more information about MyST markdown, check\n", 38 | "out [the MyST guide in Jupyter Book](https://jupyterbook.org/content/myst.html),\n", 39 | "or see [the MyST markdown documentation](https://myst-parser.readthedocs.io/en/latest/).\n", 40 | "\n", 41 | "## Code blocks and outputs\n", 42 | "\n", 43 | "Jupyter Book will also embed your code blocks and output in your book.\n", 44 | "For example, here's some sample Matplotlib code:" 45 | ] 46 | }, 47 | { 48 | "cell_type": "code", 49 | "execution_count": null, 50 | "metadata": {}, 51 | "outputs": [], 52 | "source": [ 53 | "from matplotlib import rcParams, cycler\n", 54 | "import matplotlib.pyplot as plt\n", 55 | "import numpy as np\n", 56 | "plt.ion()" 57 | ] 58 | }, 59 | { 60 | "cell_type": "code", 61 | "execution_count": null, 62 | "metadata": {}, 63 | "outputs": [], 64 | "source": [ 65 | "# Fixing random state for reproducibility\n", 66 | "np.random.seed(19680801)\n", 67 | "\n", 68 | "N = 10\n", 69 | "data = [np.logspace(0, 1, 100) + np.random.randn(100) + ii for ii in range(N)]\n", 70 | "data = np.array(data).T\n", 71 | "cmap = plt.cm.coolwarm\n", 72 | "rcParams['axes.prop_cycle'] = cycler(color=cmap(np.linspace(0, 1, N)))\n", 73 | "\n", 74 | "\n", 75 | "from matplotlib.lines import Line2D\n", 76 | "custom_lines = [Line2D([0], [0], color=cmap(0.), lw=4),\n", 77 | " Line2D([0], [0], color=cmap(.5), lw=4),\n", 78 | " Line2D([0], [0], color=cmap(1.), lw=4)]\n", 79 | "\n", 80 | "fig, ax = plt.subplots(figsize=(10, 5))\n", 81 | "lines = ax.plot(data)\n", 82 | "ax.legend(custom_lines, ['Cold', 'Medium', 'Hot']);" 83 | ] 84 | }, 85 | { 86 | "cell_type": "markdown", 87 | "metadata": {}, 88 | "source": [ 89 | "There is a lot more that you can do with outputs (such as including interactive outputs)\n", 90 | "with your book. For more information about this, see [the Jupyter Book documentation](https://jupyterbook.org)" 91 | ] 92 | } 93 | ], 94 | "metadata": { 95 | "kernelspec": { 96 | "display_name": "Python 3", 97 | "language": "python", 98 | "name": "python3" 99 | }, 100 | "language_info": { 101 | "codemirror_mode": { 102 | "name": "ipython", 103 | "version": 3 104 | }, 105 | "file_extension": ".py", 106 | "mimetype": "text/x-python", 107 | "name": "python", 108 | "nbconvert_exporter": "python", 109 | "pygments_lexer": "ipython3", 110 | "version": "3.8.0" 111 | }, 112 | "widgets": { 113 | "application/vnd.jupyter.widget-state+json": { 114 | "state": {}, 115 | "version_major": 2, 116 | "version_minor": 0 117 | } 118 | } 119 | }, 120 | "nbformat": 4, 121 | "nbformat_minor": 4 122 | } 123 | -------------------------------------------------------------------------------- /{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/references.bib: -------------------------------------------------------------------------------- 1 | --- 2 | --- 3 | 4 | @inproceedings{holdgraf_evidence_2014, 5 | address = {Brisbane, Australia, Australia}, 6 | title = {Evidence for {Predictive} {Coding} in {Human} {Auditory} {Cortex}}, 7 | booktitle = {International {Conference} on {Cognitive} {Neuroscience}}, 8 | publisher = {Frontiers in Neuroscience}, 9 | author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Knight, Robert T.}, 10 | year = {2014} 11 | } 12 | 13 | @article{holdgraf_rapid_2016, 14 | title = {Rapid tuning shifts in human auditory cortex enhance speech intelligibility}, 15 | volume = {7}, 16 | issn = {2041-1723}, 17 | url = {http://www.nature.com/doifinder/10.1038/ncomms13654}, 18 | doi = {10.1038/ncomms13654}, 19 | number = {May}, 20 | journal = {Nature Communications}, 21 | author = {Holdgraf, Christopher Ramsay and de Heer, Wendy and Pasley, Brian N. and Rieger, Jochem W. and Crone, Nathan and Lin, Jack J. and Knight, Robert T. and Theunissen, Frédéric E.}, 22 | year = {2016}, 23 | pages = {13654}, 24 | file = {Holdgraf et al. - 2016 - Rapid tuning shifts in human auditory cortex enhance speech intelligibility.pdf:C\:\\Users\\chold\\Zotero\\storage\\MDQP3JWE\\Holdgraf et al. - 2016 - Rapid tuning shifts in human auditory cortex enhance speech intelligibility.pdf:application/pdf} 25 | } 26 | 27 | @inproceedings{holdgraf_portable_2017, 28 | title = {Portable learning environments for hands-on computational instruction using container-and cloud-based technology to teach data science}, 29 | volume = {Part F1287}, 30 | isbn = {978-1-4503-5272-7}, 31 | doi = {10.1145/3093338.3093370}, 32 | abstract = {© 2017 ACM. There is an increasing interest in learning outside of the traditional classroom setting. This is especially true for topics covering computational tools and data science, as both are challenging to incorporate in the standard curriculum. These atypical learning environments offer new opportunities for teaching, particularly when it comes to combining conceptual knowledge with hands-on experience/expertise with methods and skills. Advances in cloud computing and containerized environments provide an attractive opportunity to improve the effciency and ease with which students can learn. This manuscript details recent advances towards using commonly-Available cloud computing services and advanced cyberinfrastructure support for improving the learning experience in bootcamp-style events. We cover the benets (and challenges) of using a server hosted remotely instead of relying on student laptops, discuss the technology that was used in order to make this possible, and give suggestions for how others could implement and improve upon this model for pedagogy and reproducibility.}, 33 | author = {Holdgraf, Christopher Ramsay and Culich, A. and Rokem, A. and Deniz, F. and Alegro, M. and Ushizima, D.}, 34 | year = {2017}, 35 | keywords = {Teaching, Bootcamps, Cloud computing, Data science, Docker, Pedagogy} 36 | } 37 | 38 | @article{holdgraf_encoding_2017, 39 | title = {Encoding and decoding models in cognitive electrophysiology}, 40 | volume = {11}, 41 | issn = {16625137}, 42 | doi = {10.3389/fnsys.2017.00061}, 43 | abstract = {© 2017 Holdgraf, Rieger, Micheli, Martin, Knight and Theunissen. Cognitive neuroscience has seen rapid growth in the size and complexity of data recorded from the human brain as well as in the computational tools available to analyze this data. This data explosion has resulted in an increased use of multivariate, model-based methods for asking neuroscience questions, allowing scientists to investigate multiple hypotheses with a single dataset, to use complex, time-varying stimuli, and to study the human brain under more naturalistic conditions. These tools come in the form of “Encoding” models, in which stimulus features are used to model brain activity, and “Decoding” models, in which neural features are used to generated a stimulus output. Here we review the current state of encoding and decoding models in cognitive electrophysiology and provide a practical guide toward conducting experiments and analyses in this emerging field. Our examples focus on using linear models in the study of human language and audition. We show how to calculate auditory receptive fields from natural sounds as well as how to decode neural recordings to predict speech. The paper aims to be a useful tutorial to these approaches, and a practical introduction to using machine learning and applied statistics to build models of neural activity. The data analytic approaches we discuss may also be applied to other sensory modalities, motor systems, and cognitive systems, and we cover some examples in these areas. In addition, a collection of Jupyter notebooks is publicly available as a complement to the material covered in this paper, providing code examples and tutorials for predictive modeling in python. The aimis to provide a practical understanding of predictivemodeling of human brain data and to propose best-practices in conducting these analyses.}, 44 | journal = {Frontiers in Systems Neuroscience}, 45 | author = {Holdgraf, Christopher Ramsay and Rieger, J.W. and Micheli, C. and Martin, S. and Knight, R.T. and Theunissen, F.E.}, 46 | year = {2017}, 47 | keywords = {Decoding models, Encoding models, Electrocorticography (ECoG), Electrophysiology/evoked potentials, Machine learning applied to neuroscience, Natural stimuli, Predictive modeling, Tutorials} 48 | } 49 | 50 | @book{ruby, 51 | title = {The Ruby Programming Language}, 52 | author = {Flanagan, David and Matsumoto, Yukihiro}, 53 | year = {2008}, 54 | publisher = {O'Reilly Media} 55 | } --------------------------------------------------------------------------------