Merge pull request #40 from executablebooks/update-licenses

🔧 MAINTAIN: add CC licenses and update template files

.github/workflows/tests.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]  # currently not testing on windows
-        python-version: [3.8]
+        python-version: [3.9]
     steps:
     - uses: actions/checkout@v2
     # Setup

README.md

@@ -3,7 +3,7 @@
 ![tests](https://github.com/executablebooks/cookiecutter-jupyter-book/workflows/tests/badge.svg)
 ![deploy](https://github.com/executablebooks/cookiecutter-jupyter-book/workflows/deploy/badge.svg)
 [![release](https://img.shields.io/github/release/executablebooks/cookiecutter-jupyter-book.svg)](https://github.com/executablebooks/cookiecutter-jupyter-book/releases)
-[![python](https://img.shields.io/badge/python-3.7%2C%203.8-blue)]()
+[![python](https://img.shields.io/badge/python-3.8%2C%203.9%2C%203.10-blue)]()
 [![os](https://img.shields.io/badge/OS-Ubuntu%2C%20Mac%2C%20Windows-yellow)]()
 
 <p align="center">
@@ -31,6 +31,7 @@ my_book
 │   ├── intro.md
 │   ├── logo.png
 │   ├── markdown.md
+│   ├── markdown-notebooks.md
 │   ├── notebooks.ipynb
 │   └── references.bib
 ├── README.md
@@ -51,20 +52,20 @@ $ pip install -U cookiecutter jupyter-book
 $ cookiecutter [email protected]:executablebooks/cookiecutter-jupyter-book.git
 
 author_name [Captain Jupyter]: Tomas Beuzen
-github_or_gitlab_username [tomasbeuzen]:
+github_username [tomasbeuzen]:
 book_name [My Book]:
 book_slug [my_book]:
 book_short_description [This cookiecutter creates a simple boilerplate for a Jupyter Book.]: My first Jupyter Book!
 version ['0.1.0']:
 Select open_source_license:
 1 - MIT license
 2 - BSD license
-3 - ISC license
-4 - Apache Software License 2.0
-5 - GNU General Public License v3
+3 - Apache Software License 2.0
+4 - CC BY 4.0
+5 - CC BY-SA 4.0
 6 - None
 Choose from 1, 2, 3, 4, 5, 6 [1]:
-Select include_ci_files:
+Select include_ci:
 1 - github
 2 - gitlab
 3 - no

cookiecutter.json

@@ -8,9 +8,9 @@
   "open_source_license": [
     "MIT license",
     "BSD license",
-    "ISC license",
     "Apache Software License 2.0",
-    "GNU General Public License v3",
+    "CC BY 4.0",
+    "CC BY-SA 4.0",
     "None"
   ],
   "include_ci": [

tests/test_cookiecutter.py

@@ -35,7 +35,7 @@ def test_cookiecutter_all_options(base_command, open_source_license, include_ci)
     path = Path(base_command[1])
     result = subprocess.run(base_command[0] + params, shell=True)
     assert result.returncode == 0
-    assert num_items(path, ["my_book", "my_book"]) == 8
+    assert num_items(path, ["my_book", "my_book"]) == 9
     if open_source_license == "None":
         if include_ci == "github":
             assert num_items(path, ["my_book", ".github", "workflows"]) == 1
@@ -64,7 +64,7 @@ def test_jupyter_book_cookiecutter(base_command):
     assert path.joinpath("my_book", "my_book", "_config.yml").exists()
     assert num_items(path, ["my_book"]) == 7
     assert num_items(path, ["my_book", ".github", "workflows"]) == 1
-    assert num_items(path, ["my_book", "my_book"]) == 8
+    assert num_items(path, ["my_book", "my_book"]) == 9
 
 
 @mark.parametrize(

{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/_toc-legacy.yml

@@ -6,3 +6,4 @@
   sections:
     - file: markdown
     - file: notebooks
+    - file: markdown-notebooks

{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/_toc.yml

@@ -6,3 +6,4 @@ root: intro
 chapters:
 - file: markdown
 - file: notebooks
+- file: markdown-notebooks

{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/intro.md

@@ -2,15 +2,10 @@
 
 This is a small sample book to give you a feel for how book content is
 structured.
-
-:::{note}
-Here is a note!
-:::
-
-And here is a code block:
-
-```
-e = mc^2
-```
+It shows off a few of the major file types, as well as some sample content.
+It does not go in-depth into any particular topic - check out [the Jupyter Book documentation](https://jupyterbook.org) for more information.
 
 Check out the content pages bundled with this sample book to see more.
+
+```{tableofcontents}
+```

{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/markdown-notebooks.md

@@ -0,0 +1,54 @@
+---
+jupytext:
+  cell_metadata_filter: -all
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.11.5
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Notebooks with MyST Markdown
+
+Jupyter Book also lets you write text-based notebooks using MyST Markdown.
+See [the Notebooks with MyST Markdown documentation](https://jupyterbook.org/file-types/myst-notebooks.html) for more detailed instructions.
+This page shows off a notebook written in MyST Markdown.
+
+## An example cell
+
+With MyST Markdown, you can define code cells with a directive like so:
+
+```{code-cell}
+print(2 + 2)
+```
+
+When your book is built, the contents of any `{code-cell}` blocks will be
+executed with your default Jupyter kernel, and their outputs will be displayed
+in-line with the rest of your content.
+
+```{seealso}
+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).
+```
+
+## Create a notebook with MyST Markdown
+
+MyST Markdown notebooks are defined by two things:
+
+1. YAML metadata that is needed to understand if / how it should convert text files to notebooks (including information about the kernel needed).
+   See the YAML at the top of this page for example.
+2. The presence of `{code-cell}` directives, which will be executed with your book.
+
+That's all that is needed to get started!
+
+## Quickly add YAML metadata for MyST Notebooks
+
+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:
+
+```
+jupyter-book myst init path/to/markdownfile.md
+```

{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/markdown.md

@@ -3,6 +3,7 @@
 Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or
 in regular markdown files (`.md`), you'll write in the same flavor of markdown
 called **MyST Markdown**.
+This is a simple file to help you get started and show off some syntax.
 
 ## What is MyST?
 
@@ -11,7 +12,9 @@ is a slight variation on a flavor of markdown called "CommonMark" markdown,
 with small syntax extensions to allow you to write **roles** and **directives**
 in the Sphinx ecosystem.
 
-## What are roles and directives?
+For more about MyST, see [the MyST Markdown Overview](https://jupyterbook.org/content/myst.html).
+
+## Sample Roles and Directives
 
 Roles and directives are two of the most powerful tools in Jupyter Book. They
 are kind of like functions, but written in a markup language. They both
@@ -20,59 +23,18 @@ serve a similar purpose, but **roles are written in one line**, whereas
 and what they do with those inputs depends on the specific role or directive
 that is being called.
 
-### Using a directive
-
-At its simplest, you can insert a directive into your book's content like so:
-
-````
-```{mydirectivename}
-My directive content
-```
-````
-
-This will only work if a directive with name `mydirectivename` already exists
-(which it doesn't). There are many pre-defined directives associated with
-Jupyter Book. For example, to insert a note box into your content, you can
-use the following directive:
-
-````
-```{note}
-Here is a note
-```
-````
-
-This results in:
+Here is a "note" directive:
 
 ```{note}
 Here is a note
 ```
 
-In your built book.
-
-For more information on writing directives, see the
-[MyST documentation](https://myst-parser.readthedocs.io/).
-
-
-### Using a role
-
-Roles are very similar to directives, but they are less-complex and written
-entirely on one line. You can insert a role into your book's content with
-this pattern:
-
-```
-Some content {rolename}`and here is my role's content!`
-```
-
-Again, roles will only work if `rolename` is a valid role's name. For example,
-the `doc` role can be used to refer to another page in your book. You can
-refer directly to another page by its relative path. For example, the
-role syntax `` {doc}`intro` `` will result in: {doc}`intro`.
+It will be rendered in a special box when you build your book.
 
-For more information on writing roles, see the
-[MyST documentation](https://myst-parser.readthedocs.io/).
+Here is an inline directive to refer to a document: {doc}`markdown-notebooks`.
 
 
-### Adding a citation
+## Citations
 
 You can also cite references that are stored in a `bibtex` file. For example,
 the following syntax: `` {cite}`holdgraf_evidence_2014` `` will render like
@@ -84,42 +46,10 @@ render properly.
 For example, if the references for your book are stored in `references.bib`,
 then the bibliography is inserted with:
 
-````
-```{bibliography}
-```
-````
-
-Resulting in a rendered bibliography that looks like:
-
 ```{bibliography}
 ```
 
+## Learn more
 
-### Executing code in your markdown files
-
-If you'd like to include computational content inside these markdown files,
-you can use MyST Markdown to define cells that will be executed when your
-book is built. Jupyter Book uses *jupytext* to do this.
-
-First, add Jupytext metadata to the file. For example, to add Jupytext metadata
-to this markdown page, run this command:
-
-```
-jupyter-book myst init markdown.md
-```
-
-Once a markdown file has Jupytext metadata in it, you can add the following
-directive to run the code at build time:
-
-````
-```{code-cell}
-print("Here is some code to execute")
-```
-````
-
-When your book is built, the contents of any `{code-cell}` blocks will be
-executed with your default Jupyter kernel, and their outputs will be displayed
-in-line with the rest of your content.
-
-For more information about executing computational content with Jupyter Book,
-see [The MyST-NB documentation](https://myst-nb.readthedocs.io/).
+This is just a simple starter to get you started.
+You can learn a lot more at [jupyterbook.org](https://jupyterbook.org).