├── .pre-commit-config.yaml ├── CHANGELOG.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── cookiecutter.json ├── hooks └── post_gen_project.py ├── requirements.txt ├── tests └── test_cookiecutter.py └── {{cookiecutter.repo_name}} ├── .github └── workflows │ └── deploy.yml ├── .gitignore ├── .gitlab-ci.yml ├── CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── _config.yml ├── _toc.yml ├── fav.ico ├── index.md ├── logo.png ├── requirements.txt └── {{cookiecutter.book_dir}} ├── .jupytext.toml ├── bibliography.md ├── markdown.md ├── notebooks.ipynb └── references.bib /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | repos: 2 | - repo: https://github.com/pre-commit/pre-commit-hooks 3 | rev: v4.6.0 4 | hooks: 5 | - id: check-toml 6 | # - id: check-yaml 7 | - id: end-of-file-fixer 8 | types: [python] 9 | - id: trailing-whitespace 10 | - id: requirements-txt-fixer 11 | - id: check-added-large-files 12 | args: ["--maxkb=500"] 13 | 14 | - repo: https://github.com/psf/black 15 | rev: 24.4.2 16 | hooks: 17 | - id: black-jupyter 18 | language_version: python3.11 19 | 20 | - repo: https://github.com/codespell-project/codespell 21 | rev: v2.3.0 22 | hooks: 23 | - id: codespell 24 | args: ["--ignore-words", ".codespell-ignore"] 25 | files: '\\.py$' 26 | 27 | - repo: https://github.com/kynan/nbstripout 28 | rev: 0.7.1 29 | hooks: 30 | - id: nbstripout 31 | -------------------------------------------------------------------------------- /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 for 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 | ![deploy](https://github.com/giswqs/jupyter-book-demo/workflows/deploy/badge.svg) 4 | [![os](https://img.shields.io/badge/OS-Ubuntu%2C%20Mac%2C%20Windows-yellow)]() 5 | 6 | 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/). 7 | 8 | ## Template 9 | 10 | An example template created by this cookiecutter is shown below: 11 | 12 | ``` 13 | my_book 14 | ├── .github 15 | │ └── workflows 16 | │ └── deploy.yml 17 | ├── CONDUCT.md 18 | ├── CONTRIBUTING.md 19 | ├── LICENSE 20 | ├── my_book 21 | │ ├── _config.yml 22 | │ ├── _toc.yml 23 | │ ├── fav.ico 24 | │ ├── logo.png 25 | │ ├── bibliography.md 26 | │ ├── markdown.md 27 | │ ├── notebooks.ipynb 28 | │ └── references.bib 29 | ├── README.md 30 | ├── index.md 31 | └── requirements.txt 32 | ``` 33 | 34 | ## Usage 35 | 36 | 1. Install [Cookiecutter](https://github.com/cookiecutter/cookiecutter/tree/1.7.2) if you haven't installed it yet: 37 | 38 | ```bash 39 | $ pip install -U cookiecutter 40 | ``` 41 | 42 | 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): 43 | 44 | ```bash 45 | $ cookiecutter gh:giswqs/cookiecutter-jupyter-book 46 | 47 | author_name [Captain Jupyter]: Tomas Beuzen 48 | github_or_gitlab_username [tomasbeuzen]: 49 | book_title [My Book]: 50 | repo_name [my-book]: 51 | book_short_description [This cookiecutter creates a simple boilerplate for a Jupyter Book.]: My first Jupyter Book! 52 | version ['0.1.0']: 53 | Select open_source_license: 54 | 1 - MIT license 55 | 2 - BSD license 56 | 3 - ISC license 57 | 4 - Apache Software License 2.0 58 | 5 - GNU General Public License v3 59 | 6 - None 60 | Choose from 1, 2, 3, 4, 5, 6 [1]: 61 | Select include_ci_files: 62 | 1 - github 63 | 2 - gitlab 64 | 3 - no 65 | Choose from 1, 2, 3 [1]: 66 | ``` 67 | 68 | 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/)): 69 | 70 | ```bash 71 | # Optional steps to create and activate virtual environment 72 | $ conda create --name mybook python=3.9 -y 73 | $ conda activate mybook 74 | ``` 75 | 76 | ```bash 77 | $ cd my_book 78 | $ pip install -r requirements.txt 79 | ``` 80 | 81 | 4. Build the HTML render of your Jupyter Book: 82 | 83 | ```bash 84 | $ jupyter-book build my_book/ 85 | ``` 86 | 87 | 5. View your rendered book in `my_book/_build/html/index.html`. 88 | 89 | 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. 90 | 91 | 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: 92 | 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; 93 | 2. Create a new public [GitHub repository](https://github.com/new) to host your book; 94 | 3. Push your local book (including the `.github` hidden directory) to your GitHub repository. There are many ways to do this, for example: 95 | 96 | ```bash 97 | $ git init 98 | $ git add . 99 | $ git commit -m "first commit" 100 | $ git remote add origin git@github.com:/.git 101 | $ git push -u origin main 102 | ``` 103 | 104 | 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). 105 | 106 | > 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. 107 | 108 | > 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). 109 | 110 | ## Contributing 111 | 112 | 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. 113 | 114 | You can see a list of current contributors in the [contributors tab](https://github.com/executablebooks/cookiecutter-jupyter-book/graphs/contributors). 115 | 116 | ## Acknowledgements 117 | 118 | 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). 119 | -------------------------------------------------------------------------------- /cookiecutter.json: -------------------------------------------------------------------------------- 1 | { 2 | "author_name": "Captain Jupyter", 3 | "github_username": "{{ cookiecutter.author_name.lower().replace(' ', '') }}", 4 | "book_title": "My Book", 5 | "repo_name": "{{ cookiecutter.book_title.lower().replace(' ', '-') }}", 6 | "book_dir": "book", 7 | "book_short_description": "This cookiecutter creates a simple boilerplate for a Jupyter Book.", 8 | "version": "'0.1.0'", 9 | "open_source_license": [ 10 | "MIT license", 11 | "BSD license", 12 | "ISC license", 13 | "Apache Software License 2.0", 14 | "GNU General Public License v3", 15 | "None" 16 | ], 17 | "include_ci": [ 18 | "github", 19 | "gitlab", 20 | "no" 21 | ], 22 | "branch_name": [ 23 | "master", 24 | "main" 25 | ] 26 | } -------------------------------------------------------------------------------- /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.repo_name}}/_toc.yml") 87 | # rename( 88 | # "{{cookiecutter.repo_name}}/_toc-legacy.yml", 89 | # "{{cookiecutter.repo_name}}/_toc.yml", 90 | # ) 91 | # else: 92 | # remove("{{cookiecutter.repo_name}}/_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 | black[jupyter] 2 | cookiecutter 3 | jupyter-book 4 | jupytext 5 | pytest 6 | -------------------------------------------------------------------------------- /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"]) == 8 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"]) == 8 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.repo_name}}/.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: deploy 2 | 3 | on: 4 | # Trigger the workflow on push to main branch 5 | push: 6 | branches: 7 | - {{ cookiecutter.branch_name }} 8 | 9 | # This job installs dependencies, build the book, and pushes it to `gh-pages` 10 | jobs: 11 | build-and-deploy-book: 12 | runs-on: {% raw %}${{ matrix.os }}{% endraw %} 13 | strategy: 14 | matrix: 15 | os: [ubuntu-latest] 16 | python-version: [3.9] 17 | steps: 18 | - uses: actions/checkout@v2 19 | 20 | # Install dependencies 21 | - name: Set up Python {% raw %}${{ matrix.python-version }}{% endraw %} 22 | uses: actions/setup-python@v1 23 | with: 24 | python-version: {% raw %}${{ matrix.python-version }}{% endraw %} 25 | - name: Install dependencies 26 | run: | 27 | pip install -r requirements.txt 28 | 29 | # Build the book 30 | - name: Build the book 31 | run: | 32 | jupyter-book build . 33 | 34 | # Deploy the book's HTML to gh-pages branch 35 | - name: GitHub Pages action 36 | uses: peaceiris/actions-gh-pages@v3.6.1 37 | with: 38 | github_token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} 39 | publish_dir: ./_build/html -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | docs/data/ 6 | !./_build/html/CNAME 7 | _build/html/ 8 | _build/ 9 | .vscode/ 10 | private/ 11 | .ipynb_checkpoints/ 12 | 13 | # C extensions 14 | *.so 15 | 16 | # Distribution / packaging 17 | md2rst.md 18 | md2rst.rst 19 | testing/ 20 | geemap/geemap_v*.py 21 | .Python 22 | env/ 23 | build/ 24 | develop-eggs/ 25 | dist/ 26 | downloads/ 27 | eggs/ 28 | .eggs/ 29 | lib/ 30 | lib64/ 31 | parts/ 32 | sdist/ 33 | var/ 34 | wheels/ 35 | *.egg-info/ 36 | .installed.cfg 37 | *.egg 38 | 39 | # PyInstaller 40 | # Usually these files are written by a python script from a template 41 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 42 | *.manifest 43 | *.spec 44 | 45 | # Installer logs 46 | pip-log.txt 47 | pip-delete-this-directory.txt 48 | 49 | # Unit test / coverage reports 50 | htmlcov/ 51 | .tox/ 52 | .coverage 53 | .coverage.* 54 | .cache 55 | nosetests.xml 56 | coverage.xml 57 | *.cover 58 | .hypothesis/ 59 | .pytest_cache/ 60 | 61 | # Translations 62 | *.mo 63 | *.pot 64 | 65 | # Django stuff: 66 | *.log 67 | local_settings.py 68 | 69 | # Flask stuff: 70 | instance/ 71 | .webassets-cache 72 | 73 | # Scrapy stuff: 74 | .scrapy 75 | 76 | # Sphinx documentation 77 | docs/_build/ 78 | 79 | # PyBuilder 80 | target/ 81 | 82 | # Jupyter Notebook 83 | .ipynb_checkpoints 84 | 85 | # pyenv 86 | .python-version 87 | 88 | # celery beat schedule file 89 | celerybeat-schedule 90 | 91 | # SageMath parsed files 92 | *.sage.py 93 | 94 | # dotenv 95 | .env 96 | 97 | # virtualenv 98 | .venv 99 | venv/ 100 | ENV/ 101 | 102 | # Spyder project settings 103 | .spyderproject 104 | .spyproject 105 | 106 | # Rope project settings 107 | .ropeproject 108 | 109 | # mkdocs documentation 110 | /site 111 | 112 | # mypy 113 | .mypy_cache/ 114 | 115 | # IDE settings 116 | .vscode/ 117 | -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/.gitlab-ci.yml: -------------------------------------------------------------------------------- 1 | image: python:3.7 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. 28 | - mv ./_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.repo_name}}/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.repo_name}}/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_title }} could always use more documentation, whether as part of the 29 | official {{ cookiecutter.book_title }} 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_title }}` 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_title }} 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.repo_name}}/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' %} 24 | 25 | BSD License 26 | 27 | Copyright (c) {% now 'local', '%Y' %}, {{ cookiecutter.author_name }} 28 | All rights reserved. 29 | 30 | Redistribution and use in source and binary forms, with or without modification, 31 | are permitted provided that the following conditions are met: 32 | 33 | * Redistributions of source code must retain the above copyright notice, this 34 | list of conditions and the following disclaimer. 35 | 36 | * Redistributions in binary form must reproduce the above copyright notice, this 37 | list of conditions and the following disclaimer in the documentation and/or 38 | other materials provided with the distribution. 39 | 40 | * Neither the name of the copyright holder nor the names of its 41 | contributors may be used to endorse or promote products derived from this 42 | software without specific prior written permission. 43 | 44 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 45 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 46 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 47 | IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 48 | INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 49 | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 50 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 51 | OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 52 | OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 53 | OF THE POSSIBILITY OF SUCH DAMAGE. 54 | {% elif cookiecutter.open_source_license == 'ISC license' -%} 55 | ISC License 56 | 57 | Copyright (c) {% now 'local', '%Y' %}, {{ cookiecutter.author_name }} 58 | 59 | Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. 60 | 61 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 62 | {% elif cookiecutter.open_source_license == 'Apache Software License 2.0' -%} 63 | Apache Software License 2.0 64 | 65 | Copyright (c) {% now 'local', '%Y' %}, {{ cookiecutter.author_name }} 66 | 67 | Licensed under the Apache License, Version 2.0 (the "License"); 68 | you may not use this file except in compliance with the License. 69 | You may obtain a copy of the License at 70 | 71 | http://www.apache.org/licenses/LICENSE-2.0 72 | 73 | Unless required by applicable law or agreed to in writing, software 74 | distributed under the License is distributed on an "AS IS" BASIS, 75 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 76 | See the License for the specific language governing permissions and 77 | limitations under the License. 78 | {% elif cookiecutter.open_source_license == 'GNU General Public License v3' -%} 79 | GNU GENERAL PUBLIC LICENSE 80 | Version 3, 29 June 2007 81 | 82 | {{ cookiecutter.book_short_description }} 83 | Copyright (C) {% now 'local', '%Y' %} {{ cookiecutter.author_name }} 84 | 85 | This program is free software: you can redistribute it and/or modify 86 | it under the terms of the GNU General Public License as published by 87 | the Free Software Foundation, either version 3 of the License, or 88 | (at your option) any later version. 89 | 90 | This program is distributed in the hope that it will be useful, 91 | but WITHOUT ANY WARRANTY; without even the implied warranty of 92 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 93 | GNU General Public License for more details. 94 | 95 | You should have received a copy of the GNU General Public License 96 | along with this program. If not, see . 97 | 98 | Also add information on how to contact you by electronic and paper mail. 99 | 100 | You should also get your employer (if you work as a programmer) or school, 101 | if any, to sign a "copyright disclaimer" for the program, if necessary. 102 | For more information on this, and how to apply and follow the GNU GPL, see 103 | . 104 | 105 | The GNU General Public License does not permit incorporating your program 106 | into proprietary programs. If your program is a subroutine library, you 107 | may consider it more useful to permit linking proprietary applications with 108 | the library. If this is what you want to do, use the GNU Lesser General 109 | Public License instead of this License. But first, please read 110 | . 111 | {% endif %} 112 | -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/README.md: -------------------------------------------------------------------------------- 1 | # {{ cookiecutter.book_title }} 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_title }} 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.repo_name }}/` directory 14 | 4. Run `jupyter-book clean {{ cookiecutter.repo_name }}/` to remove any existing builds 15 | 5. Run `jupyter-book build {{ cookiecutter.repo_name }}/` 16 | 17 | A fully-rendered HTML version of the book will be built in `{{ cookiecutter.repo_name }}/_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.repo_name }}/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.repo_name}}/_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_title }} # 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 | # Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb") 13 | exclude_patterns: [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints"] 14 | # Auto-exclude files not in the toc 15 | only_build_toc_files: true 16 | 17 | # Force re-execution of notebooks on each build. 18 | # See https://jupyterbook.org/content/execute.html 19 | execute: 20 | execute_notebooks: "auto" # Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off") 21 | cache: "" # A path to the jupyter cache that will be used to store execution artifacts. Defaults to `_build/.jupyter_cache/` 22 | exclude_patterns: [] # A list of patterns to *skip* in execution (e.g. a notebook that takes a really long time) 23 | timeout: 100 # The maximum time (in seconds) each notebook cell is allowed to run. 24 | run_in_temp: 25 | false # If `True`, then a temporary directory will be created and used as the command working directory (cwd), 26 | # otherwise the notebook's parent directory will be the cwd. 27 | allow_errors: false # If `False`, when a code cell raises an error the execution is stopped, otherwise all cells are always run. 28 | stderr_output: show # One of 'show', 'remove', 'remove-warn', 'warn', 'error', 'severe' 29 | 30 | launch_buttons: 31 | colab_url: "https://colab.research.google.com" 32 | notebook_interface: "jupyterlab" 33 | binderhub_url: "https://mybinder.org" 34 | 35 | # Information about where the book exists on the web 36 | repository: 37 | url: https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.repo_name }} # Online location of your book 38 | # path_to_book: docs # Optional path to your book, relative to the repository root 39 | branch: main # Which branch of the repository should be used when creating links (optional) 40 | 41 | # Add GitHub buttons to your book 42 | # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository 43 | html: 44 | favicon: "fav.ico" 45 | baseurl: https://{{ cookiecutter.github_username }}.github.io/{{ cookiecutter.repo_name }} # The base URL where your book will be hosted. 46 | use_repository_button: true 47 | use_issues_button: true 48 | use_edit_page_button: true 49 | use_download_button: true 50 | # thebe: true 51 | # google_analytics_id: G-XXXXXXX 52 | 53 | sphinx: 54 | config: 55 | # html_extra_path: ["CNAME", "robots.txt"] 56 | html_theme_options: 57 | use_download_button: true 58 | repository_url: https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.repo_name }} 59 | use_issues_button: true 60 | use_repository_button: true 61 | use_edit_page_button: true 62 | launch_buttons: 63 | { 64 | binderhub_url: "https://mybinder.org", 65 | colab_url: "https://colab.research.google.com", 66 | } 67 | bibtex_reference_style: author_year 68 | 69 | 70 | # Define the name of the latex output file for PDF builds 71 | # latex: 72 | # latex_documents: 73 | # targetname: book.tex 74 | 75 | 76 | # Add a bibtex file so that we can create citations 77 | bibtex_bibfiles: 78 | - {{ cookiecutter.book_dir }}/references.bib 79 | -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/_toc.yml: -------------------------------------------------------------------------------- 1 | # Table of contents 2 | # Learn more at https://jupyterbook.org/customize/toc.html 3 | 4 | format: jb-book 5 | root: index 6 | chapters: 7 | - file: {{ cookiecutter.book_dir }}/markdown 8 | - file: {{ cookiecutter.book_dir }}/notebooks 9 | - file: {{ cookiecutter.book_dir }}/bibliography 10 | 11 | # Or you organize the TOC by parts 12 | 13 | # parts: 14 | # - caption: Chapters 15 | # numbered: true 16 | # maxdepth: 2 17 | # chapters: 18 | # - file: book/markdown 19 | # - file: book/notebooks 20 | # - caption: Appendices 21 | # chapters: 22 | # - file: book/bibliography -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/fav.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/giswqs/cookiecutter-jupyter-book/11af40eb6e357add43fbc4c3f27827a0dae9591d/{{cookiecutter.repo_name}}/fav.ico -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/index.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 | 6 | :::{note} 7 | Here is a note! 8 | ::: 9 | 10 | And here is a code block: 11 | 12 | ``` 13 | e = mc^2 14 | ``` 15 | 16 | Check out the content pages bundled with this sample book to see more. 17 | -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/giswqs/cookiecutter-jupyter-book/11af40eb6e357add43fbc4c3f27827a0dae9591d/{{cookiecutter.repo_name}}/logo.png -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/requirements.txt: -------------------------------------------------------------------------------- 1 | jupyter-book 2 | jupytext 3 | matplotlib 4 | numpy 5 | {% if cookiecutter.include_ci == 'github' -%}ghp-import{% endif %} 6 | -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/{{cookiecutter.book_dir}}/.jupytext.toml: -------------------------------------------------------------------------------- 1 | # Install jupytext using: conda install jupytext -c conda-forge 2 | # Always pair ipynb notebooks to md files. 3 | # formats = "ipynb,md" 4 | formats = "ipynb,myst" 5 | 6 | # jupytext --to ipynb *.md # convert all .md files to notebooks with no outputs 7 | # jupytext --to ipynb --execute *.md # convert all .md files to notebooks and execute them 8 | # jupytext --set-formats ipynb,md --execute *.md # convert all .md files to paired notebooks and execute them 9 | # jupytext --to md *.ipynb # convert all .ipynb files to .md files -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/{{cookiecutter.book_dir}}/bibliography.md: -------------------------------------------------------------------------------- 1 | # Bibliography 2 | 3 | ```{bibliography} 4 | 5 | ``` 6 | -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/{{cookiecutter.book_dir}}/markdown.md: -------------------------------------------------------------------------------- 1 | --- 2 | jupytext: 3 | text_representation: 4 | extension: .md 5 | format_name: myst 6 | format_version: 0.13 7 | jupytext_version: 1.11.5 8 | kernelspec: 9 | display_name: Python 3 10 | language: python 11 | name: python3 12 | --- 13 | 14 | 15 | # Markdown Files 16 | 17 | Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or 18 | in regular markdown files (`.md`), you'll write in the same flavor of markdown 19 | called **MyST Markdown**. 20 | 21 | ## What is MyST? 22 | 23 | MyST stands for "Markedly Structured Text". It 24 | is a slight variation on a flavor of markdown called "CommonMark" markdown, 25 | with small syntax extensions to allow you to write **roles** and **directives** 26 | in the Sphinx ecosystem. 27 | 28 | ## What are roles and directives? 29 | 30 | Roles and directives are two of the most powerful tools in Jupyter Book. They 31 | are kind of like functions, but written in a markup language. They both 32 | serve a similar purpose, but **roles are written in one line**, whereas 33 | **directives span many lines**. They both accept different kinds of inputs, 34 | and what they do with those inputs depends on the specific role or directive 35 | that is being called. 36 | 37 | ### Using a directive 38 | 39 | At its simplest, you can insert a directive into your book's content like so: 40 | 41 | ```` 42 | ```{mydirectivename} 43 | My directive content 44 | ``` 45 | ```` 46 | 47 | This will only work if a directive with name `mydirectivename` already exists 48 | (which it doesn't). There are many pre-defined directives associated with 49 | Jupyter Book. For example, to insert a note box into your content, you can 50 | use the following directive: 51 | 52 | ```` 53 | ```{note} 54 | Here is a note 55 | ``` 56 | ```` 57 | 58 | This results in: 59 | 60 | ```{note} 61 | Here is a note 62 | ``` 63 | 64 | In your built book. 65 | 66 | For more information on writing directives, see the 67 | [MyST documentation](https://myst-parser.readthedocs.io/). 68 | 69 | ### Using a role 70 | 71 | Roles are very similar to directives, but they are less-complex and written 72 | entirely on one line. You can insert a role into your book's content with 73 | this pattern: 74 | 75 | ``` 76 | Some content {rolename}`and here is my role's content!` 77 | ``` 78 | 79 | Again, roles will only work if `rolename` is a valid role's name. For example, 80 | the `doc` role can be used to refer to another page in your book. You can 81 | refer directly to another page by its relative path. For example, the 82 | role syntax `` {doc}`index` `` will result in: {doc}`index`. 83 | 84 | For more information on writing roles, see the 85 | [MyST documentation](https://myst-parser.readthedocs.io/). 86 | 87 | ### Adding a citation 88 | 89 | You can also cite references that are stored in a `bibtex` file. For example, 90 | the following syntax: `` {cite}`holdgraf_evidence_2014` `` will render like 91 | this: {cite}`holdgraf_evidence_2014`. 92 | 93 | Multiple citations can be used like this: 94 | {cite}`holdgraf_rapid_2016, holdgraf_encoding_2017` 95 | 96 | Moreover, you can insert a bibliography into your page with this syntax: 97 | The `{bibliography}` directive must be used for all the `{cite}` roles to 98 | render properly. 99 | For example, if the references for your book are stored in `references.bib`, 100 | then the bibliography is inserted with: 101 | 102 | ```` 103 | ```{bibliography} 104 | ``` 105 | ```` 106 | 107 | Resulting in a rendered bibliography that looks like: 108 | 109 | 112 | 113 | ### Executing code in your markdown files 114 | 115 | If you'd like to include computational content inside these markdown files, 116 | you can use MyST Markdown to define cells that will be executed when your 117 | book is built. Jupyter Book uses _jupytext_ to do this. 118 | 119 | First, add Jupytext metadata to the file. For example, to add Jupytext metadata 120 | to this markdown page, run this command: 121 | 122 | ``` 123 | jupyter-book myst init markdown.md 124 | ``` 125 | 126 | Once a markdown file has Jupytext metadata in it, you can add the following 127 | directive to run the code at build time: 128 | 129 | ```` 130 | ```{code-cell} 131 | print("Here is some code to execute") 132 | ``` 133 | ```` 134 | 135 | When your book is built, the contents of any `{code-cell}` blocks will be 136 | executed with your default Jupyter kernel, and their outputs will be displayed 137 | in-line with the rest of your content. 138 | 139 | For more information about executing computational content with Jupyter Book, 140 | see [The MyST-NB documentation](https://myst-nb.readthedocs.io/). 141 | -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/{{cookiecutter.book_dir}}/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 | "\n", 57 | "plt.ion()" 58 | ] 59 | }, 60 | { 61 | "cell_type": "code", 62 | "execution_count": null, 63 | "metadata": {}, 64 | "outputs": [], 65 | "source": [ 66 | "# Fixing random state for reproducibility\n", 67 | "np.random.seed(19680801)\n", 68 | "\n", 69 | "N = 10\n", 70 | "data = [np.logspace(0, 1, 100) + np.random.randn(100) + ii for ii in range(N)]\n", 71 | "data = np.array(data).T\n", 72 | "cmap = plt.cm.coolwarm\n", 73 | "rcParams[\"axes.prop_cycle\"] = cycler(color=cmap(np.linspace(0, 1, N)))\n", 74 | "\n", 75 | "\n", 76 | "from matplotlib.lines import Line2D\n", 77 | "\n", 78 | "custom_lines = [\n", 79 | " Line2D([0], [0], color=cmap(0.0), lw=4),\n", 80 | " Line2D([0], [0], color=cmap(0.5), lw=4),\n", 81 | " Line2D([0], [0], color=cmap(1.0), lw=4),\n", 82 | "]\n", 83 | "\n", 84 | "fig, ax = plt.subplots(figsize=(10, 5))\n", 85 | "lines = ax.plot(data)\n", 86 | "ax.legend(custom_lines, [\"Cold\", \"Medium\", \"Hot\"]);" 87 | ] 88 | }, 89 | { 90 | "cell_type": "markdown", 91 | "metadata": {}, 92 | "source": [ 93 | "There is a lot more that you can do with outputs (such as including interactive outputs)\n", 94 | "with your book. For more information about this, see [the Jupyter Book documentation](https://jupyterbook.org)" 95 | ] 96 | } 97 | ], 98 | "metadata": { 99 | "kernelspec": { 100 | "display_name": "Python 3", 101 | "language": "python", 102 | "name": "python3" 103 | }, 104 | "language_info": { 105 | "codemirror_mode": { 106 | "name": "ipython", 107 | "version": 3 108 | }, 109 | "file_extension": ".py", 110 | "mimetype": "text/x-python", 111 | "name": "python", 112 | "nbconvert_exporter": "python", 113 | "pygments_lexer": "ipython3", 114 | "version": "3.8.0" 115 | } 116 | }, 117 | "nbformat": 4, 118 | "nbformat_minor": 4 119 | } 120 | -------------------------------------------------------------------------------- /{{cookiecutter.repo_name}}/{{cookiecutter.book_dir}}/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 | } --------------------------------------------------------------------------------