diff --git a/.github/workflows/call-deploy-book.yml b/.github/workflows/call-deploy-book.yml index 76ccb8d..5d8d291 100644 --- a/.github/workflows/call-deploy-book.yml +++ b/.github/workflows/call-deploy-book.yml @@ -4,7 +4,7 @@ on: push: branches: - '**' - # If your git repository has the Jupyter Book within some-subfolder next to + # If your git repository has the TeachBook or Jupyter Book v1 within some-subfolder next to # unrelated files, you can make this run only if a file within that specific # folder (or the workflow file itself) has been modified. # diff --git a/README.md b/README.md index ef47f47..28ddb35 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ Set the repository website as your GitHub Pages website under {octicon}`code;1em ``` ## Features -- A github repository structure for making a [Jupyter Book](https://github.com/executablebooks/jupyter-book) (`/book`) +- A github repository structure (`/book`) for making a TeachBook: a [Jupyter Book v1](https://github.com/executablebooks/jupyter-book) for educational purposes - An empty TeachBook containing an intro page on root, an example markdown page, an example jupyter notebook page, an example references page. and an example credits page. (`/book/_toc.yml`, `/book/_config.yml`, `/book/credits.md`, `/book/intro.md`, `/book/references.md`, `/book/some_content/overview.md`, `/book/some_content/text_and_code.ipynb`) - A file ready for adding references (`references.bib`, `/book/references.md`) - An example favicon (web browser icon) (`/book/figures/favicon.ico`, `book/_config.yml`.) diff --git a/book/_config.yml b/book/_config.yml index 4453ecc..a918b00 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,19 +1,19 @@ -# This config includes all the recommended (default) configuration options of the TeachBooks software, and a TeachBooks' selection of configuration options as provided by Jupyter Book for Jupyter Book software and Sphinx. +# This config includes all the recommended (default) configuration options of the TeachBooks software, and a TeachBooks' selection of configuration options as provided by Jupyterbook v1 for Jupyterbook v1 software and Sphinx. author: TeachBooks Team, built with TeachBooks, CC BY 4.0 # Replace TeachBooks Teams with your own name in the line above, configuratin part of JupyterBook: https://jupyterbook.org/en/stable/customize/config.html execute: - execute_notebooks: "off" # Replace this if you want don't have notebooks with output and you want to add notebook output during build, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - cache: "_build/.jupyter_cache/" # Default value (line can be removed), sets path to the jupyter cache that will be used to store execution artifacts, doesn't work in GitHub workflow, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - exclude_patterns: [] # Default value (line can be removed), sets a list of patterns to *skip* in execution, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html), can overwritten by Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) - timeout: 30 # Default value (line can be removed), sets he maximum time (in seconds) each notebook cell is allowed to run, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - run_in_temp: false # Default value (line can be removed), disables a temporary directory was the command working directory (cwd), configuration part Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - allow_errors: false # Default value (line can be removed), all cells are always run, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - stderr_output: show # Default value (line can be removed), shows stderr output, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + execute_notebooks: "off" # Replace this if you want don't have notebooks with output and you want to add notebook output during build, configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) + cache: "_build/.jupyter_cache/" # Default value (line can be removed), sets path to the jupyter cache that will be used to store execution artifacts, doesn't work in GitHub workflow, configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) + exclude_patterns: [] # Default value (line can be removed), sets a list of patterns to *skip* in execution, configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html), can overwritten by Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) + timeout: 30 # Default value (line can be removed), sets he maximum time (in seconds) each notebook cell is allowed to run, configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) + run_in_temp: false # Default value (line can be removed), disables a temporary directory was the command working directory (cwd), configuration part Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) + allow_errors: false # Default value (line can be removed), all cells are always run, configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) + stderr_output: show # Default value (line can be removed), shows stderr output, configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) html: - use_multitoc_numbering : true # Default value (line can be removed), sets continuous numbering across parts/chapters, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html). Same functionality per section can be defined with sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) - extra_footer : "" # Default value (line can be removed), sets text to be displayed underneath the footer, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + use_multitoc_numbering : true # Default value (line can be removed), sets continuous numbering across parts/chapters, configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html). Same functionality per section can be defined with sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html) + extra_footer : "" # Default value (line can be removed), sets text to be displayed underneath the footer, configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) sphinx: # Options passed on to the underlying sphinx-parser extra_extensions: # Sets a list of extensions to load by sphinx, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) @@ -33,15 +33,15 @@ sphinx: # Options passed on to the text: Template # Replace this with your own book title, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark), configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light), configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) - repository_url: "https://github.com/user/repo" # Add your own repo URL here, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - path_to_docs: "book" # Required for edit_page_button, should be book if you're using TeachBooks package (https://github.com/TeachBooks/TeachBooks) or the TeachBooks deploy book workflow (https://teachbooks.io/manual/external/deploy-book-workflow/README.html), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - repository_branch: "main" # Replace when you change the name of your published branch (required for edit_page_button), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - use_edit_page_button: true # Replace with false if you don't want the edit page button (i.e. if you don't user to propose changes themselves or have a private repo), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - use_repository_button: true # Replace with false if you don't want the repository button (i.e. if you have a private repo), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) - use_issues_button : true # Replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + repository_url: "https://github.com/user/repo" # Add your own repo URL here, configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) + path_to_docs: "book" # Required for edit_page_button, should be book if you're using TeachBooks package (https://github.com/TeachBooks/TeachBooks) or the TeachBooks deploy book workflow (https://teachbooks.io/manual/external/deploy-book-workflow/README.html), configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) + repository_branch: "main" # Replace when you change the name of your published branch (required for edit_page_button), configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) + use_edit_page_button: true # Replace with false if you don't want the edit page button (i.e. if you don't user to propose changes themselves or have a private repo), configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) + use_repository_button: true # Replace with false if you don't want the repository button (i.e. if you have a private repo), configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) + use_issues_button : true # Replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo), configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) launch_buttons: thebe: true # Required for live code, part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html) - announcement: "" # Default value (line can be removed), sets a banner announcement at the top of the site, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html) + announcement: "" # Default value (line can be removed), sets a banner announcement at the top of the site, configuration part of Jupyterbook v1 (https://jupyterbook.org/en/stable/customize/config.html) html_show_copyright: false # As the copyright is included in the author field, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) html_last_updated_fmt: '%B %-d, %Y' # Adds the date of the last update to the footer, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) html_static_path: ["figures"] # Add folder that contain files that need to be included, such as the location of the logo(s), configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html) diff --git a/book/exercises.md b/book/exercises.md index cca212a..69756b6 100644 --- a/book/exercises.md +++ b/book/exercises.md @@ -1,6 +1,6 @@ # Exercises TeachBooks workflow -Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you as part. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages. We welcome you to work through the exercises attached to this page (you can find them in the left sidebar). +Getting used to the syntax of writing in a TeachBook can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you as part. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages. We welcome you to work through the exercises attached to this page (you can find them in the left sidebar). ```{tip} Maybe you're already comfortable with Git, GitHub and the concept of using software to parse text-based files and create marked-up documents. In that case, can you answer the following questions (referring to the exercises): diff --git a/book/exercises/003.md b/book/exercises/003.md index e2c630a..9b15b62 100644 --- a/book/exercises/003.md +++ b/book/exercises/003.md @@ -12,7 +12,7 @@ Can you edit the repository url defined in the `_config.yml`, change the title s :class: tip, dropdown The first line of your `_config.yml` should look like ```yaml -author: , built with TeachBooks and Jupyter Book, CC BY 4.0 +author: TeachBooks Team, built with TeachBooks, CC BY 4.0 ``` ```` 3. In the `Edit` field, change the title of your homepage which will under the logo and above the table of contents diff --git a/book/extension_exercises/014.md b/book/extension_exercises/014.md index 8724c83..cdde661 100644 --- a/book/extension_exercises/014.md +++ b/book/extension_exercises/014.md @@ -2,7 +2,7 @@ With live coding you can make your pages more interactive by adding live, executable code cells. This extension is already part of your TeachBooks book if you started from the template. If not, you can follow instructions [in the manual](https://teachbooks.io/manual/features/live_code.html#setting-up-python-live-coding) to enable it. The template also includes a sample page with live code enabled, which you can find [here for the website of the original template](https://teachbooks.io/template/some_content/text_and_code.html) -With live code enabled, readers can run snippets directly in the browser, experiment with examples, and complete exercises in real time. This section will guide you through some of the main features available: additional cell tags have been developed that can be added to Python code cells in your book. These tags extend the [existing Jupyter Book tags](https://jupyterbook.org/en/stable/content/metadata.html) and allow you to control how cells behave when live execution is enabled. +With live code enabled, readers can run snippets directly in the browser, experiment with examples, and complete exercises in real time. This section will guide you through some of the main features available: additional cell tags have been developed that can be added to Python code cells in your book. These tags extend the [existing Jupyter Book v1 tags](https://jupyterbook.org/en/stable/content/metadata.html) and allow you to control how cells behave when live execution is enabled. ::::::{topic} Exercise objective Can you apply custom cell tags to control the execution and visibility of code cells? diff --git a/book/syntax_exercises.md b/book/syntax_exercises.md index 9f43c06..5b8ab6a 100644 --- a/book/syntax_exercises.md +++ b/book/syntax_exercises.md @@ -2,6 +2,6 @@ The previous exercise guide you through making your own book following the TeachBooks workflow. Now lets get specific and dive into the possibilities of the syntax used! -As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In Jupyter Book, `.md` files contain text-based content with formatting, while `ipynb` files contain both text and executable code cells. `.md` files are much easier to edit online, so let's start with those! +As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In TeachBooks, `.md` files contain text-based content with formatting, while `ipynb` files contain both text and executable code cells. `.md` files are much easier to edit online, so let's start with those! -The more you write, the more different types of content you'll want to use. [JupyterBook itself provides a cheatsheet](https://jupyterbook.org/v1/reference/cheatsheet.html) which will come in handy! \ No newline at end of file +The more you write, the more different types of content you'll want to use. [JupyterBook v1 itself provides a cheatsheet](https://jupyterbook.org/v1/reference/cheatsheet.html) which will come in handy! \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 0479af9..ee1cf09 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ # first list the packages you wish to download from PyPI -teachbooks # depends on jupyter-book +teachbooks # depends on jupyter-book v1 # Our favourite Sphinx extensions in one line, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites) git+https://github.com/TeachBooks/TeachBooks-Favourites