diff --git a/.gitignore b/.gitignore index 72818e9..1d59fdc 100644 --- a/.gitignore +++ b/.gitignore @@ -135,3 +135,6 @@ _contents/ # Jupyterlite _output/ book/.jupyterlite.doit.db + +# TeachBooks +**.teachbooks/ \ No newline at end of file diff --git a/.gitmodules b/.gitmodules index 208f06a..f76fc05 100644 --- a/.gitmodules +++ b/.gitmodules @@ -7,15 +7,9 @@ [submodule "book/external/deploy-book-workflow"] path = book/external/deploy-book-workflow url = https://github.com/TeachBooks/deploy-book-workflow.git -[submodule "book/external/latex-to-markdown-conversion"] - path = book/external/latex-to-markdown-conversion - url = https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion.git [submodule "book/external/Useful_python_code"] path = book/external/Useful_python_code url = https://github.com/TeachBooks/Useful_python_code.git -[submodule "book/external/TeachBooks"] - path = book/external/TeachBooks - url = https://github.com/TeachBooks/TeachBooks.git [submodule "book/external/Sphinx-Image-Inverter"] path = book/external/Sphinx-Image-Inverter url = https://github.com/TeachBooks/Sphinx-Image-Inverter.git diff --git a/README.md b/README.md index c92464c..92cb94d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # TeachBooks Manual +[![call-deploy-book](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml/badge.svg)](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml) + This manual assists you in creating and collaborating on [JupyterBooks](https://jupyterbook.org/) for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start and advanced usages for new and existing users with or without skills on this topic. it is part of TeachBooks, for more information visit [https://teachbooks.io/](https://teachbooks.io/). ## Contact @@ -16,4 +18,4 @@ The released book can be found on on https://teachbooks.io/manual. This page sho Some parts of this book are taken from other sources in the form of submodules (linked in the folder [book/external](book/external)). To contribute to those pages, contribute to the source repository directly with a fork and merge/pull request. If you intent to clone this boko including its submodules, clone using: `git clone --recurse-submodules git@github.com:TeachBooks/manual.git` -Happy book building! \ No newline at end of file +Happy book building! diff --git a/book/_config.yml b/book/_config.yml index 0075cab..8c6fa4e 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -18,6 +18,7 @@ sphinx: - jupyterbook_patches - teachbooks_sphinx_grasple - sphinx_image_inverter + - sphinx_exercise config: html_js_files: - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js @@ -27,8 +28,8 @@ sphinx: html_theme_options: logo: text: Manual - image_light: TB_logo.png - image_dark: TB_logo_dark.png + image_light: TeachBooks_logo.svg + image_dark: TeachBooks_logo_inverted.svg repository_url: "https://github.com/TeachBooks/manual/" path_to_docs: "book" repository_branch: "release" diff --git a/book/_toc.yml b/book/_toc.yml index e3e13aa..19512bf 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -2,7 +2,21 @@ format: jb-book root: intro parts: - - caption: Getting started! + - caption: Your First TeachBook! + chapters: + - file: intro/book.md + - file: intro/workflow.md + - file: intro/template.md + sections: + - file: external/template/book/exercises/001.md + - file: external/template/book/exercises/002.md + - file: external/template/book/exercises/003.md + - file: external/template/book/exercises/004.md + - file: external/template/book/exercises/005.md + - file: external/template/book/exercises/006.md + - file: intro/workshop/summary + - file: intro/next.md + - caption: Getting Going! chapters: - file: installation-and-setup/user_types.md - file: installation-and-setup/git.md @@ -13,7 +27,6 @@ parts: - file: installation-and-setup/anaconda.md - file: installation-and-setup/git_bash_conda_vs-code.md - file: installation-and-setup/jupyter-book-setup.md - - file: external/template/README.md - file: workflows/collaboration.md sections: - file: workflows/milestones_issues.md @@ -43,19 +56,18 @@ parts: - file: basic-features/Code_block_figures - file: basic-features/banner title: Banner or Announcement - - file: basic-features/external-features.md - sections: - - file: basic-features/hypothesis.md - - file: basic-features/utterances.md - file: features/easy-editing.md sections: - - file: external/TeachBooks/README.md + - file: external/template/README.md + - file: features/teachbooks - file: external/deploy-book-workflow/README.md + - file: features/local_server - file: external/Nested-Books/README.md - file: features/sphinx_extensions.md sections: - file: external/Download-Link-Replacer/README.md - - file: features/custom-launch-button.md + - file: features/custom-launch-button.md + - file: basic-features/utterances.md - file: features/interactive_element.ipynb sections: - file: external/Sphinx-Grasple-public/README.md @@ -74,9 +86,11 @@ parts: - file: external/JupyterBook-Patches/README.md - file: external/Sphinx-TUDelft-theme/README.md - file: external/teachbooks-sphinx-tippy/README.md + - file: features/apa - file: features/students sections: - file: external/annotater/README.md + - file: basic-features/hypothesis.md - caption: Examples chapters: @@ -90,12 +104,11 @@ parts: - file: examples/coding_theory_widgets.ipynb - file: examples/parametric_questions.ipynb - - caption: Editing tools + - caption: Editing Tools chapters: - file: tools/figmaker - file: helper_code/intro.md sections: - - file: external/latex-to-markdown-conversion/README.md - file: external/Useful_python_code/snippit.ipynb - file: external/Useful_python_code/extensionfildownloadreturn.ipynb - file: external/Useful_python_code/figshrinker.ipynb diff --git a/book/basic-features/external-features.md b/book/basic-features/external-features.md deleted file mode 100644 index d574b30..0000000 --- a/book/basic-features/external-features.md +++ /dev/null @@ -1,8 +0,0 @@ -# Externally Developed Features - -```{admonition} User types -:class: tip -This section is useful for user type 1-5. -``` - -This chapter includes features useful for books in the educational context, developed by various parties. \ No newline at end of file diff --git a/book/basic-features/hypothesis.md b/book/basic-features/hypothesis.md index 1d490ce..0f42e79 100644 --- a/book/basic-features/hypothesis.md +++ b/book/basic-features/hypothesis.md @@ -1,5 +1,10 @@ # Making comments on the website: Hypothesis +```{admonition} User types +:class: tip +This section is useful for user type 1-5. +``` + {bdg-warning}`Javascript overlay` {bdg-success}`Chrome Extension` Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension. As this tool requires an account with a third-party, we advise to use our [local-annotator](../external/annotater/README.md) with similar capabilities but which store annotations locally. By default Hypothesis stores annotations publicly, which might confuse other students. diff --git a/book/basic-features/utterances.md b/book/basic-features/utterances.md index c6e9593..f82a44f 100644 --- a/book/basic-features/utterances.md +++ b/book/basic-features/utterances.md @@ -1,5 +1,10 @@ # Discussions in your book: Utterances +```{admonition} User types +:class: tip +This section is useful for user type 3-5. +``` + {bdg-white}`GitHub app and Javascript script` [Utterances ๐Ÿ”ฎ](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab). diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index 5c129f2..edbfec1 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit 5c129f2447bb4b30100c136d94b5bee9e51e2921 +Subproject commit edbfec1142870af35032e18f301fcd9f9edc16e7 diff --git a/book/external/Nested-Books b/book/external/Nested-Books index ced5cde..c2ebd1f 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit ced5cdefa1b1b6c4fdba3fc42a94e812db4892f0 +Subproject commit c2ebd1fdad5abddb62d7f4c876f2f20d88d23f49 diff --git a/book/external/Sphinx-TUDelft-theme b/book/external/Sphinx-TUDelft-theme index a7a87d4..8b86de6 160000 --- a/book/external/Sphinx-TUDelft-theme +++ b/book/external/Sphinx-TUDelft-theme @@ -1 +1 @@ -Subproject commit a7a87d4d4c9dc3839af49104492048724d1e6191 +Subproject commit 8b86de655b4bc808f58cefbe65971d4e16453995 diff --git a/book/external/TeachBooks b/book/external/TeachBooks deleted file mode 160000 index eb5f90c..0000000 --- a/book/external/TeachBooks +++ /dev/null @@ -1 +0,0 @@ -Subproject commit eb5f90c86e6f9dd368c513b2d958f77fb941cae0 diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index 71dd5f2..f2feadf 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit 71dd5f2f56c8540fa45ce713adf44cab9d85c36e +Subproject commit f2feadf1c39103311e98afdbda588f51d5e361c4 diff --git a/book/external/latex-to-markdown-conversion b/book/external/latex-to-markdown-conversion deleted file mode 160000 index cb81691..0000000 --- a/book/external/latex-to-markdown-conversion +++ /dev/null @@ -1 +0,0 @@ -Subproject commit cb8169156e5c0150848cf52fb177d0d40934522e diff --git a/book/external/template b/book/external/template index 9c54cdf..4a5f1c8 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 9c54cdf1ccbfdb8bfb4b79090b83019f00cfc828 +Subproject commit 4a5f1c8983241cc78d9fc91ba925d50402e9f558 diff --git a/book/features/_ext.zip b/book/features/_ext.zip new file mode 100644 index 0000000..34e2f8f Binary files /dev/null and b/book/features/_ext.zip differ diff --git a/book/features/adding_HTML_elements.md b/book/features/adding_HTML_elements.md index b241964..78a6cf0 100644 --- a/book/features/adding_HTML_elements.md +++ b/book/features/adding_HTML_elements.md @@ -32,7 +32,7 @@ Let's take a closer look at the source. Since this project uses a local file str - Finally, the string `"element_render_box.html"` selects the HTML file we want to embed. We are now in `book/_static/element_render_box.html`. ## Viewing result at local build -To view the final result locally, it's required to setup a [local python webserver](setup-local-server). +To view the final result locally, it's required to setup a {ref}`local Python webserver `. ## HTML code for the 3D render element @@ -196,4 +196,4 @@ To conclude, I provide the HTML/JavaScript code for the 3D render element above. -``` \ No newline at end of file +``` diff --git a/book/features/apa.md b/book/features/apa.md new file mode 100644 index 0000000..2135569 --- /dev/null +++ b/book/features/apa.md @@ -0,0 +1,97 @@ +# APA References + +```{admonition} User types +:class: tip +This page is useful for user type 4 and 5. +``` + +{bdg-primary}`(To be converted into) Sphinx Extension` + +```{note} +This feature is stable but because it relies on a local extension that is part of your book files and _not_ managed as part of a computing environment (e.g., `pip` or `conda`), unknown issues may arise. We would like to convert this feature into an independent Sphinx extension and/or Pybtext plugin. Visit the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17) to learn more. + +The instructions provided here will work under conventional usage with Jupyter Book (e.g., `jupyter book build book`). + +A temporary fix has also been implemented in the TeachBooks package for use with the Deploy Book Workflow (release mode) (see [release notes from v0.1.0](https://github.com/TeachBooks/TeachBooks/releases/tag/v0.1.0)). +``` + +## Introduction + +Do you include references in your book, but you're tired of the default options available in Jupyter Book? For example, the square-bracket style of citation and reference, where the first three letters of the name year are combined in a way that seems designed to minimize transparency? + +There is a solution! This extension allows you to have APA formatting in your book. + +## Installation +To use APA-references, a set of Python files need to be manually loaded into your book + +**Step 1: files to root directory of your book** + +Download this zip-file [`_ext.zip`](_ext.zip), which contains the necessary files, unzip it and place the contents in the root of your book directory so that it looks like the schematic here: + +``` +book +โ”œโ”€โ”€ _ext/ +โ”‚ โ”œโ”€โ”€ pybtexapastyle/ +โ”‚ โ”œโ”€โ”€ apastyle.py +โ”‚ โ”œโ”€โ”€ bracket_citation_style.py +โ”œโ”€โ”€ _config.yml +โ”œโ”€โ”€ _toc.yml +โ”œโ”€โ”€ requirements.txt +โ”œโ”€โ”€ +``` + +**Step 2: Add to `requirements.txt`** + +Add a specific version of `docutils` to your requirements file: +``` +docutils==0.17.1 +``` + +**Step 3: Enable in `_config.yml`** + +In your `_config.yml` file, add a `bibtex_default_style`, `bybtex_reference_style` and the local extensions `apastyle` and `bracket_citation_style.py` +``` +sphinx: + config: + ... + bibtex_default_style: myapastyle + bibtex_reference_style: author_year_round + local_extensions: + apastyle: _ext/ + bracket_citation_style: _ext/ + ... +``` + +## Usage + +All references are now made in APA-style. See for example this reference: {cite:t}`jason_moore` which shows up on the [references page](../references.md) too. The form of the citation looks like this: + +``` +{cite:t}`jason_moore` +``` + +Here are three examples for making citations: + +| Syntax | Result | +| :---: | :---: | +|`{cite:t}` | {cite:t}`jason_moore` | +|`{cite:p}`| {cite:p}`jason_moore` | +|`{cite}`| {cite}`jason_moore` | + +For more options on the in-line citation style, see https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style. + +### Known Issue + +During the build, warning will be raised with `... WARNING: duplicate label for keys ...`. In most cases, these warnings can be ignored. As noted above, the book will not build references properly + +## Implementation + +The extension is based on [`pybtex`](https://pybtex.org/), which is a BibTeX-compatible bibliography processor in Python that is extendible with plugins. + +Although some customization is possible with the standard Jupyter Book features, [as described here](https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style), this extension implements the complete APA style, as well as enforcing round brackets (like this). + +The need to enforce `docutils==0.17.1` version is the only known solution to the issue where empty brackets `[]` are left on the references page. + +## Contribute + +This tool needs to be developed further to make it into a proper sphinx-extension (and/or an independent `pybtext` plugin). The process is described in this [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17). If you've ideas or questions, please reach out to us at info@teachbooks.io! \ No newline at end of file diff --git a/book/features/custom-launch-button.md b/book/features/custom-launch-button.md index 8df830b..b935a7c 100644 --- a/book/features/custom-launch-button.md +++ b/book/features/custom-launch-button.md @@ -96,7 +96,7 @@ The code in the above cell is the `_launch_buttons.yml` file of a repository cal ```{figure} figures/language_button.PNG --- width: 50% -name:language_button +name: language_button --- Custom Button ``` diff --git a/book/features/local_server.md b/book/features/local_server.md new file mode 100644 index 0000000..cea8930 --- /dev/null +++ b/book/features/local_server.md @@ -0,0 +1,95 @@ +(setup-local-server)= +# Local Server to view interactive elements locally + +```{admonition} User types +:class: tip +This section is useful for user type 4-5. +``` + +{bdg-secondary}`Python Package` + +Perhaps you have already noticed that when building a book and testing it locally on your computer, some features do not work the way you expect, or worse---do not work at all! This is because many interactive features rely on browser functionality to work properly, for example: Grasple/H5p iframe exercises, Sphinx-Thebe Python interactivity and HTML/Javascript elements. Although the website is _static_ (i.e., there is no code running on a webserver that generates the content), modern web browsers have their own internal computing environments that run processes to deliver the rich content we desire in our books. + +Technically what is needed to facilitate this during the editing and checking of your book locally is a **static web server** that can serve the files in the `./book/_build/html` directory of your book (this subdirectory is created as a result of the command `build book`). We refer to this as a **local server** because it is running on your local machine. + +```{admonition} Why do you need a local server? +:class: tip + +A Jupyter Book is really just a _static website._ This means that all book content _and interactivity_ is available via the (static) files that are provided to you by a webserver when you visit a specific URL. After this initial request, all required files are available in your web browser, however, some features require the request and response protocol to work properly. +``` + +We recommend you use the **TeachBooks Python Package**, which has a `serve` command in the CLI tool to start and stop local servers. Find out more on {ref}`the TeachBooks Package page `. + +This page presents just a few additional examples that are used by TeachBooks collaborators. There are many more options available out there, for example, [this list illustrates many servers that can be activated with a single line of code!](https://gist.github.com/willurd/5720255). + +```{tip} +Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated. + +You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. +``` + +## TeachBooks Server: `teachbooks serve` + +If you have the TeachBooks Python package installed (`pip install teachbooks`), starting a server is as simple as: + +```bash +teachbooks serve +``` + +See the {ref}`TeachBooks Package page ` for additional guidance on using the CLI tool. + +## Live Server: a VS Code Extension + +A local server is easy to initialize directly in VS Code using the Live Server extension. Once installed, it can be activated with a "Go Live" button in the bottom right corner of VS Code. The extension will automatically serve index.html, so depending on your book build settings you may need to navigate to the correct directory/file manually using the URL address in the browser. + +````{admonition} Install Live Serve Extension +:class: tip + +You can install this extension by searching for `Live Server` (or even easier, extension ID `ritwickdey.LiveServer`)in the Visual Studio Code extensions marketplace. + +```{figure} https://github.com/ritwickdey/live-server-web-extension/raw/master/img/icon.png +--- +width: 10% +name: live-server-icon +``` +```` + + +## Python Server: `python -m http.server` + +The Python standard library has a built-in server that can be activated from the command line. This is a simple way to serve a book locally + +``` +python -m http.server +``` + +If you don't mind typing a bit more, you can specify the port number and the directory to serve: + +``` +python -m http.server 8000 --directory book/_build/html +``` + +This is actually what the `teachbooks serve` command is using, but there we have added additional features to make the process more user-friendly for the book edit and check workflow. + +### Stopping the Python Server + +It can be challenging to stop the Python server, especially when using Windows OS. Even though you may force end the process (e.g., with `CMD+C`), the server may still be running in the background. + +For Mac and Linux users (or for Windows if you have Git Bash installed or another Unix-type terminal), you can try this: + +```bash +pid=$(ps aux | grep http.server | head -n 1 | awk '{ print $2 }') +kill -9 $pid +``` + +Or this: + +```bash +tskill python +``` + +A Windows-specific command for the CMD prompt or Powershell is: + +``` +TASKKILL /IM python.exe /F +``` \ No newline at end of file diff --git a/book/features/overview.md b/book/features/overview.md index 30d40b8..7ad3782 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -1,8 +1,13 @@ # Overview -As TeachBooks, we collect a suite of existing open-source software and keep our books up-to-date so you don't have to! Some of the software is developed with our TA's to improve the learning experience of our students and ease the book-development process for our teachers. By deploying these tools from a central location we can prevent common problems before they arise, and fix them quickly when they do occur. As the open-source software landscape changes rapidly, it is essential to keep in contact and share resources amongst ourselves to minimize maintenance and downtime for our book websites and focus on what really matters: teaching! +As TeachBooks, we collect a suite of existing open-source software so you don't have to! Some of the software is developed with our TA's to improve the learning experience of our students and ease the book-development process for our teachers. As the open-source software landscape changes rapidly, it is essential to keep in contact and share resources amongst ourselves to minimize maintenance and downtime for our book websites and focus on what really matters: teaching! Since the list of TeachBook features is getting quite long, we have grouped them in categories: +- Original Jupyter Book and Sphinx features +- Easy editing process +- Additional functionality +- Book styling +- TeachBooks student-view features Additionally, not all features are built using the same type of sourcecode. For transparency, tags will help differentiate between the different backgrounds of the features: - {bdg-warning}`Javascript overlay` @@ -10,6 +15,7 @@ Additionally, not all features are built using the same type of sourcecode. For - {bdg-white}`GitHub App and Javascript script` - {bdg-secondary}`Python Package` - {bdg-light}`GitHub Reusable Action` +- {bdg-light}`GitHub Template` - {bdg-dark}`Git Workflow` - {bdg-primary}`Sphinx Extension` - {bdg-danger}`iframe` diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index 244f3ff..4caf9a8 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -1,18 +1,144 @@ (teachbooks-package)= -# TeachBooks: Our Custom Python Package +# Pre- and postprocessing book + +```{admonition} User types +:class: tip +This page is useful for all users to understand how the book building process works and can be influenced, although the implementation is likely going to be carried out by User Types 3, 4 or 5. +``` + +{bdg-secondary}`Python Package` + +The package is a CLI tool that primarily provides a wrapper around the Jupyter Book package which is used for pre- and postprocessing. In this case "wrapper" refers to the CLI usage: CLI commands generally invoke `jupyter-book` commands internally; the `jupyter-book` package is _not_ distributed within the `teachbooks` package. + +The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction. + +## Primary Features + +Key features (described in the sections below) include: +- pre- and post-processing steps for the Jupyter Book package +- Draft-Release Workflow (`teachbooks build --release book`) +- Start and stop a local server to check your book (`teachbooks serve`) + +This list will be updated periodically as features are added. Check the [Release Notes](https://github.com/TeachBooks/TeachBooks/releases) in the GitHub repository for the most up-to-date information. + +## Installation + +The package is currently only [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows: -TeachBooks has created a Python package and released it on PyPI. It can easily be used like this: ``` pip install teachbooks ``` -The source code is hosted in a repository on GitHub, [github.com/teachBooks/teachbooks](https://github.com/teachBooks/teachbooks), and is accompanied by a documentation website, [teachbooks.github.io/TeachBooks/](https://teachbooks.github.io/TeachBooks/). +The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly: -The features and documentation will increase with time; until then, note there are two important reasons to use the teachbooks package: -1. Use the `REMOVE-FROM-PUBLISH` feature to more easily maintain draft and published versions of your TeachBook (see {ref}`this page ` for more details). -2. Easily start and stop a local Python server to better test your book while writing (e.g., the interactive Python features require a local server to properly check certain TeachBooks features) +```bash +pip install --upgrade teachbooks +``` -For case 1, the `teachbooks` package is meant to be used instead of `jupyter book build book` to build your book (it executes `jupyter book build book` for you). +We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow `. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice. -Case 2 is meant to be used independently, for example, once you have successfully built a book, simply run `teachbooks serve` and open the resulting URL that is printed in the terminal. To stop the server use `teachbooks serve stop`; see {ref}`this page ` for additional explanation for how to use this feature and why it is needed. +## Contribute +This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). The `README.md` of the repository describes how you can contribute---don't hesitate to make an issue if you would like to request new features! + +## Description of Features + +(teachbooks-pre-post)= +### Jupyter Book Pre- and Post-Processing + +Using the teachbooks CLI in the book building process generally invokes Jupyter Book. Many of the features in this package are then invoked in the stages before and after this command. The process generally includes the following steps: + +1. Edit source code and prepare to build a book +2. Execute `teachbooks [OPTIONS] COMMAND [ARGS]` +3. Pre-processing step: carried out by `teachbooks` +4. Build step: book is built using `jupyter book [OPTIONS] COMMAND [ARGS]` +5. Post-processing step: carried out by `teachbooks` + +Additional options like those used in jupyterbook (`--all` for example) can be used with `teachbooks` in an identical usage as with the `jupyter-book` command. + +```{note} +The pre- and post-processing steps have not yet bet formally defined; they only exist implicitly in the source code for the `build` CLI command. If you are interested in suggesting a feature or contributing to the package, please visit the [GitHub repository](https://github.com/teachbooks/teachbooks) and take a look at the Discussions and Issues. For example, [this one](https://github.com/orgs/TeachBooks/discussions/28). +``` + +(teachbooks-draft-release)= +### Draft-Release Workflow + +Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}Deploy Book Workflow `, which builds our TeachBooks). + +```{admonition} Why is this useful? +:class: tip + +Consider a case where you have been using two branches to develop and maintain a book: `release` (shared with students) and `draft` (shared with colleagues to review contents before release). You are probably also using other branches to develop contents, but rely on the `draft` branch as a way to collect the "finalized-but-not-yet-released" material. Things go smoothly as long as you add pages to the `draft` branch one at a time, then merge the branch into `release` as they are needed. + +But what happens when you have 2 pages: one is ready to share with students, but the other is still being reviewed by your colleague. The only way to get the proper page into release is to comment the undesired page in the ToC using a commit on `draft`, merge the commit into `release`, then uncomment the ToC in a new commit on `draft`. This is very tedious, and prone to error as there it is not straightforward to tell which pages are available in the `draft` versus `release` books! + +The Draft-Release workflow solves this problem by using commented tags to clearly denote which pages are available in the `draft` book and which are left out of the `release` book. +``` + +The workflow is enabled by a `teachbooks` CLI feature that identifies and removes any lines from the files `_config.yml` and `_toc.yml` file that are surrounded by `REMOVE-FROM-RELEASE` tags. + +For example, pages in a developed book (e.g., `draft` branch) can be manually stripped out of the table of contents when a merge request from `draft` to `release` is made. This prevents the page being included in the released book. Pages marked with this feature are still visible in the `draft` book. Lines tagged in the configuration file `_config.yml` can be used in exactly the same manner. The tag is applied as follows: + +``` +format: jb-book +root: intro + +parts: + - caption: ... + chapters: + - file: ... + ... +# START REMOVE-FROM-PUBLISH + - file: files_to_remove +# END REMOVE-FROM-PUBLISH +``` + +There is no limit to the number of stripped sections, they can be sequential and indentation does not matter. + +To invoke the tag and remove content during the book build process, use the following optional argument when building the book with the `teachbooks` package: + +``` +teachbooks build --publish book +``` + +Note that `teachbooks build book` would build a book without stripping the tagged lines, just as `jupyter-book build book` would. This is called "draft mode" and is the default behavior. You can recognize it in the stdout after running the `build` command: + +```bash +TeachBooks: running build with strategy 'draft' +``` + +(teachbooks-serve)= +### Local Python server + +```{tip} +Visit the {ref}`Local Server page ` for an explanation of why you need a local server. +``` + +The TeachBooks Python package includes a command line interface (CLI) that can be used to start a local server: + +```bash +teachbooks serve +``` +By default it assumes you have a book in `./book/`, are running the command from the root `./` of your repository and will serve `./book/_build/html`. If not, it will serve the repository root. You can also specify the directory to serve: + +```bash +teachbooks serve path unconventional_book_dir/_build/html +``` + +```{tip} +Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated. + +You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. +``` + +To stop the server, simply run + +```bash +teachbooks serve stop +``` + +The CLI tool is set up to make the book edit and check workflow as easy as possible locally: +- you can rebuild the book without restarting the server. +- it reuses an existing server if already running. +- it prints the URL where the book is served after building the book to easily access it by clicking the link in standard output. +- the `teachbooks serve stop` command prevents Python processes running in the backgroudn and slowing down your computer (it saves the server state in a pickle file). \ No newline at end of file diff --git a/book/helper_code/intro.md b/book/helper_code/intro.md index c5e7c38..0886e9e 100644 --- a/book/helper_code/intro.md +++ b/book/helper_code/intro.md @@ -1,7 +1,6 @@ # Scripts for automating workflow This chapter contains a few scripts which can be useful in the book-editing process: - - [LaTeX to markdown conversion](../external/latex-to-markdown-conversion/README.md) to convert a LaTeX file into jupyter-book compatible markdown. - [Snippitall](Snippitall) to insert the same code snippet at a certain point in each md file in a specific folder and all subfolder. - [Snippitonce](Snippitonce) to insert the same code snippet at a certain point in each md file only in a specific folder. - [Extensionchecker](Extensionchecker) to identify the kind of files present in subfolder diff --git a/book/images/TB_logo.png b/book/images/TB_logo.png deleted file mode 100644 index 976df66..0000000 Binary files a/book/images/TB_logo.png and /dev/null differ diff --git a/book/images/TB_logo_dark.png b/book/images/TB_logo_dark.png deleted file mode 100644 index ac75575..0000000 Binary files a/book/images/TB_logo_dark.png and /dev/null differ diff --git a/book/images/TeachBooks_logo.svg b/book/images/TeachBooks_logo.svg new file mode 100644 index 0000000..7f59513 --- /dev/null +++ b/book/images/TeachBooks_logo.svg @@ -0,0 +1,80 @@ + + + + + + + + + + \ No newline at end of file diff --git a/book/images/TeachBooks_logo_inverted.svg b/book/images/TeachBooks_logo_inverted.svg new file mode 100644 index 0000000..dd9bc38 --- /dev/null +++ b/book/images/TeachBooks_logo_inverted.svg @@ -0,0 +1,81 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/book/installation-and-setup/copyright.md b/book/installation-and-setup/copyright.md index 5da3081..604c8ba 100644 --- a/book/installation-and-setup/copyright.md +++ b/book/installation-and-setup/copyright.md @@ -1,7 +1,12 @@ (copyright)= # Before the Content: Copyright and Licenses -The previous sections have familiarized you with the necessary software for your user type, the basics of Git, and how to collaborate with your team using Git. Now it's time to create your own content. This chapter provides an overview of the copyright and license considerations that should be taken into account when creating and including Jupyter Book content in any educational setting. +```{admonition} User types +:class: tip +This page is useful for user type 3-5. +``` + +The previous sections have familiarized you with the necessary software for your user type, the basics of Git, and how to collaborate with your team using Git. Now it's time to create your own content. This section will provide an overview of the copy right laws which need to be taking into account when creating and including content at TU Delft! Although the focus of TeachBooks is mostly to help the teaching staff create interactive textbooks for their students, it can be attractive to spread ones wings a bit and reach a wider audience. The checklist on this page provides a quick overview of the _minimium_ information you should be aware of when getting started in terms of copyright, avoiding legal issues and making your life easier later on when/if you decide to publish your book with an open license, for example via TU Delft Open. diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md index fb01fdf..e63b46f 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -58,7 +58,7 @@ On GitLab a webserver is required to process book-changes online. Both we and ot ### Setting up book repository and website On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md). -On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:teachbooks@tudelft.nl) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online. +On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:info@teachbooks.io) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online. ### Book access with SSO When youโ€™re releasing your book on a server on which you're in control (connected to GitLab or GitHub), you can set up SSO login for visitors of the website. This can be arranged for on the TeachBooks server. diff --git a/book/intro.md b/book/intro.md index 67e557a..7f8efc5 100644 --- a/book/intro.md +++ b/book/intro.md @@ -1,5 +1,19 @@ # TeachBooks Manual -This manual assists you in creating and collaborating on Jupyter book for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start and advanced usages for new and existing users with or without skills on this topic. it is part of TeachBooks, for more information visit [https://teachbooks.io/](https://teachbooks.io/). +This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on Jupyter book. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users. We hope you find this resource useful and refer back to it often. -Happy book building! \ No newline at end of file +TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our community beyond Delft and welcome contributions from all users. + +For more information about TeachBooks, visit [https://teachbooks.io/](https://teachbooks.io/). Do not hesitate to reach out via email at [info@teachbooks.io](mailto:teachbooks@tudelft.nl) or contribute on GitHub via discussions, issues or pull requests. + +Happy book building! + +## How to Use this Manual + +There are several "parts" to the manual: +- **Your First TeachBook!** introduces the essential platforms and workflows, and contains a _workshop_ that can be completed independently or as part of a TeachBooks training. We recommend even experienced Jupyter Book users go through this material to better understand the TeachBooks vision on how to make books collaboratively, as this drives much of our tool development. The workshop is designed to be completed in 1-2 hours and does not require any prior knowledge or installation (just a GitHub account). +- **Getting Going!** begins with an overview of _User Types_, which are used to help understand which parts of the Manual are most relevant to you. Detailed software installation instructions, book and team setup and workflows are also provided in this part. +- The **Features** part describes a suite of tools that are useful for teachers, many of which are developed by TeachBooks contributors specifically for use in education. Many of these tools are illustrated in the **Examples**. +- A few special tools are included in the **Editing Tools** that are useful when writing content. + +See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc. \ No newline at end of file diff --git a/book/intro/book.md b/book/intro/book.md new file mode 100644 index 0000000..0089f43 --- /dev/null +++ b/book/intro/book.md @@ -0,0 +1,106 @@ +# What is a TeachBook? + +Never seen a TeachBook before? Here's a small demo of our MUDE-book! + +
+
+ +
+
+ +So what are you looking at? It's a website generated with the [Jupyter Book package](https://jupyterbook.org/). Various extensions have been added to improve the student-experience, especially for technical topics! The actual website you're looking at now is a Jupyter Book. With TeachBooks we aim to make it easy to collaboratively use it, even if you've little experience with the software package which is part of it. + +## Three Key Ingredients + +To create a Jupyter Book, three key ingredients are needed: + +1. A **configuration file** to define functionalities, `_config.yml` +2. A **table of contents** file to list which files should end up in the book, `_toc.yml`, as well as define its structure +3. **Content** for your book! Text-based files which allows you to embed figures, videos, math and interactive elements. + +The files are typically organized together in a files structure like this: + +``` +โ””โ”€โ”€ my_book_directory/ + โ”œโ”€โ”€ README.md + โ”œโ”€โ”€ requirements.txt + โ””โ”€โ”€ book/ + โ””โ”€โ”€ _config.yml + โ””โ”€โ”€ _toc.yml + โ””โ”€โ”€ contents/ + โ””โ”€โ”€ intro.md + โ””โ”€โ”€ chapter1.md + โ””โ”€โ”€ chapter2.ipynb + โ””โ”€โ”€ images/ + โ””โ”€โ”€ figure1.png +``` + +Note the arrangement of the 3 key book ingredients in a subdirectory called `book/`; this is where you should focus when you are just getting started with TeachBooks and are making your first book. Additional files can be used to control the book-building process, and these are typically stored _outside_ the `book/` directory to keep the book contents separate. For now, all you need to understand that everything needed to create a book can be collected in a single top-level directory (`my_book_directory/`, in this case), and this directory is what becomes the collection of files in our Git **repository** (described elsewhere). + +`````{admonition} Text-based files? yml? What is that?! +:class: tip, dropdown + +Text-based files are digital files on your computer that you can open in a text editor and read directly. There are many file extensions used for text-based files, a few common ones related to Jupyter Book are: Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), and YAML (`*.yml`). + +YAML (or YML) is a text-based file format that is primarily used to store data. It is useful because it is easy for humans to read and write, and easy for machines to _parse_ and generate., which is why YAML is often used for configuration files. Here is an example of a YAML file...can you tell what information is being stored? + +```yaml +parts: + - caption: Your First TeachBook! + chapters: + - file: intro/book.md + - file: intro/workflow.md + - file: intro/template.md + sections: + - file: external/teachbooks.md +``` + +````{admonition} Description of the YAML file +:class: tip, dropdown + +You can see quite clearly that a number of files are listed, and that they are organized into chapters and sections. This defines the structure of the book---you can confirm this by comparing to the left sidebar, as this book is where this example YAML snippet came from! +```` +````` + +## How is a book made? + +A book is made by by writing content in text-based files such as Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), etc. After that, software is used to "parse" these files and create the final book (e.g., Jupyter Book). Fortunately when getting started you don't need to worry about the software because TeachBooks has set up GitHub tools for you that take care of this process automatically! The process is illustrated in the diagram below. + +```{figure} figures/intro-book.svg +--- +width: 700px +--- +The process of building a book with TeachBooks. When just getting started, TeachBooks tools enables you to focus on what matters most: learning to write content for your book! +``` + +```{admonition} Familiar with LaTeX? There are similarities! +:class: dropdown + +Have you ever used LaTeX? It turns out there are a lot of similarities with Jupyter Book. Here is a quick list: +1. Writing "source code" in text-based files (i.e., `*.tex` versus `*.md`, `*.ipynb`, etc) that is generally easy to read without the markup and uses special functions to format rich document objects (e.g., tables, figures, etc). +2. The "book" is created by using a piece of software that parses the source code and creates the final document (a `*.pdf` versus a `*.html` for Jupyter Book). +3. Creating the document structure using a list of files that contain source code that automatically generates the Table of Contents and Index.. +4. Sometimes you can spend more time than you like troubleshooting "bugs" that turn out to be simple syntax errors. + +If you've used LaTeX before, it will be relatively easy to learn to use a Jupyter Book. +``` + +## Why are Git and GitHub Important? + +The fun part is the collaborative aspect of TeachBooks! However, the amount of software required _when doing this by yourself_ can be intimidating. Git and GitHub are tools used by TeachBooks to make this process as smooth as possible for newcomers. + +There are three reasons why Git and GitHub are important for TeachBooks: + +1. **Version control**: Git is a version control system that allows you to track changes to your files over time. This is especially useful when you're working with others on a book, as it allows you to see who made what changes and when. +2. **Collaboration**: GitHub is a company that provides a wide array of online tools. These _augment_ the version control features incorporated directly in Git. In short, tools at `github.com` allow you to share your files with others and work on them together. This is especially useful when you're working on a book with multiple authors, as it allows you to easily share your work and collaborate. +3. **Automation**: GitHub provides a number of tools that can help automate the process of building your book. TeachBooks has carefully developed a number of these tools specifically to support teachers and students in the process of creating and sharing educational content. + +## What's next? + +The following pages will introduce you to a standard "workflow" for editing a book, which is focused entirely in the "source code" of a book (the first box in the diagram above). After we cover this, you'll be ready to make your first book! diff --git a/book/intro/figures/TeachBooks_flowchart_v04.png b/book/intro/figures/TeachBooks_flowchart_v04.png new file mode 100644 index 0000000..87e3438 Binary files /dev/null and b/book/intro/figures/TeachBooks_flowchart_v04.png differ diff --git a/book/intro/figures/branch.png b/book/intro/figures/branch.png new file mode 100644 index 0000000..cde708f Binary files /dev/null and b/book/intro/figures/branch.png differ diff --git a/book/intro/figures/check.png b/book/intro/figures/check.png new file mode 100644 index 0000000..2695af2 Binary files /dev/null and b/book/intro/figures/check.png differ diff --git a/book/intro/figures/edit.png b/book/intro/figures/edit.png new file mode 100644 index 0000000..f13eaf9 Binary files /dev/null and b/book/intro/figures/edit.png differ diff --git a/book/intro/figures/idea.png b/book/intro/figures/idea.png new file mode 100644 index 0000000..3d2a180 Binary files /dev/null and b/book/intro/figures/idea.png differ diff --git a/book/intro/figures/intro-book.svg b/book/intro/figures/intro-book.svg new file mode 100644 index 0000000..f0cde2d --- /dev/null +++ b/book/intro/figures/intro-book.svg @@ -0,0 +1,350 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Source Code(Repository)*.md, *.ipynb + + + + Online Book(webserver) + + + + html files(website) + + + + MarkupSoftwarejupyter-book + + + + + + + + + You edit text-based files(source code) + + + + TeachBooks tools and GitHub do the rest! + + + + + + diff --git a/book/intro/figures/online.png b/book/intro/figures/online.png new file mode 100644 index 0000000..6e4bb7d Binary files /dev/null and b/book/intro/figures/online.png differ diff --git a/book/intro/figures/review.png b/book/intro/figures/review.png new file mode 100644 index 0000000..b47bff0 Binary files /dev/null and b/book/intro/figures/review.png differ diff --git a/book/intro/figures/template.jpg b/book/intro/figures/template.jpg new file mode 100644 index 0000000..e3b3c6f Binary files /dev/null and b/book/intro/figures/template.jpg differ diff --git a/book/intro/next.md b/book/intro/next.md new file mode 100644 index 0000000..4fb2a20 --- /dev/null +++ b/book/intro/next.md @@ -0,0 +1,20 @@ +# You Know the Basics: What Next? + +You've seen what a JupyterBook is, how TeachBooks tries to help you with making those, and what the potential is in teaching. So what's next? + +In this manual we explain how to get going depending on the way you want to use it. If you successfully followed the steps until here, you'll be able to make book as a 'user type 3'! + +```{figure} ../installation-and-setup/figures/usertype3.jpg +--- +name: usertype1 +width: 300px +align: center +--- +User type 3 +``` + +In the next part of this manual 'Getting going!', we'll explain which options you have as more advanced user, how to collaboratively edit books en how to organize you team, tools, websites and copyright-considerations. + +Furthermore, in the 'Features' part we'll collect a suite of existing open-source software to ease the editing process, add functionalities, improve styling and improve the student-experience. Finally, the 'Examples' page contain some example pages of some book. + +We hope you enjoin making books with TeachBooks. If you encounter any problem, please reach out to us on [email](mailto:info@teachbooks.io) or our [GitHub Discussions](https://github.com/orgs/TeachBooks/discussions). We'd be happy to collaborate with you or simple receive some feedback, examples, cool ideas. Happy book building! \ No newline at end of file diff --git a/book/intro/template.md b/book/intro/template.md new file mode 100644 index 0000000..32dad92 --- /dev/null +++ b/book/intro/template.md @@ -0,0 +1,46 @@ +# It only takes 10 clicks! + +```{figure} figures/template.jpg +--- +name: template +width: 150px +align: right +``` + +Now that you've been introduced to the basics of a Jupyter Book, let's make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a Jupyter Book, as well as the tools and essential workflows associated with the editing, checking and review processes. + +## 1. Create a GitHub account +TeachBooks relies of freely available services from GitHub to store files online, carry out the book-building process and host your book as a website. All you need to get started is a GitHub account (not counted in the 10 clicks ๐Ÿคญ). + +```{exercise} + +If you don't already have one, create a GitHub account here by visiting [github.com/signup](https://github.com/signup). +``` + +## 2. Use the template---it's really just 10 clicks! +Now, let's make a book: we've made a template on GitHub which carries out _most_ of the technical steps required to create a book and put it online. Instructions for using the template are in the `README` of the TeachBooks Template repository on GitHub, which is by default visible on the repository homepage. + +```{exercise} + +Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBooks/template) and follow the instructions to create your book. At the end, it should be visible at `.github.io/`. When finished, come back to this page. +``` + +## 3. Let's practice! +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 of an introductory **workshop**. 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. + +```{exercise} +Work through the exercises attached to this page (you can find them in the left sidebar). These exercises can also be found in the template book itself. +``` + +```{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 (refering to the exercises): +1. Can you add some content to the intro page? +2. Can you add the file named `file_to_be_added_to_toc.md` to the book website? +3. Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer? +4. Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online? +5. Can you merge your branch into `main` with a pull request? +6. Can you fork someone else's repo, and suggest a change in a pull request? + +If something is not clear, dive into to the relevant exercise page. +``` + diff --git a/book/intro/workflow.md b/book/intro/workflow.md new file mode 100644 index 0000000..bc0c038 --- /dev/null +++ b/book/intro/workflow.md @@ -0,0 +1,55 @@ +# How can you do it? + +The fun part is the collaborative aspect of TeachBooks! Because all the files are text-based, they're well suited for using git. That allows us to use the version-control principles of git to its best! + +Assuming you have a book (well make that happen soon!) and you're ready to collaborate, the process is as follows: + +## 1 get an idea +```{figure} figures/idea.png +--- +width: 70px +align: right +``` +You have an idea to improve a book or add some content! Let's make that happen! Share you idea with the book-authors to let them know you're starting something! Maybe someone else has some ideas on it as well. Later on, you can use GitHub `Issues`, `Projects` and `Milestones` to keep track of this. + +## 2 create your version of the book +```{figure} figures/branch.png +--- +width: 100px +align: right +``` +Let's create a space for you idea to form. You can create your own version of the book, visible for everyone to see. On GitHub, you'll use `branches` or `forks`. + +## 3 edit the book +```{figure} figures/edit.png +--- +width: 100px +align: right +``` +Creativity activated, let's start adding content to your book! You'll add text, images, videos, math, interactive quizes, coding, widgets, etc. As editing the book is not directly done in a graphical interface with buttons like Microsoft Word, you'll need to learn a bit of syntax. The [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) will be added to your bookmarks. The changes you'll make have to be added to the GitHub version control system, creating `commits` on the your git `branch`. + +## 4 check changes +```{figure} figures/check.png +--- +width: 100px +align: right +``` +You've made a change, how does is look like? Your raw file have to be parsed. You can do that yourself or use the tooling provided by use in a GitHub `Action`. As soon as you uploaded (`pushed` in Git language) your changes to GitHub, it'll create a nice looking website for you! + +## 5 repeat, edit and check +```{figure} figures/review.png +--- +width: 100px +align: right +``` +You'll make mistakes and you'll want to alter content... many, many times... As long as your idea is not ready to be shared with other, keep iterating step 3 and 4 until it's perfect! + +## 6 submit for review +```{figure} figures/online.png +--- +width: 100px +align: right +``` +You're done! Great! Now let's see what others think of your contribution. You'll submit your changes to the original book, in GitHub language this is called a `Pull request`. Other will be able to review, adapt and eventually `merge` your version into the book! + +I hope that all of this seems fun! Let's continue on making this happen! \ No newline at end of file diff --git a/book/intro/workshop/06.md b/book/intro/workshop/06.md new file mode 100644 index 0000000..0691015 --- /dev/null +++ b/book/intro/workshop/06.md @@ -0,0 +1,13 @@ +# Exercise 6: Submit for Review + +Now we make a PR and merge it. + + +```{admonition} Check your understanding +:class: tip + +Before moving on to the next exercise, make sure you understand the following: +1. Where is the Table of Contents defined? +... +``` + diff --git a/book/intro/workshop/07.md b/book/intro/workshop/07.md new file mode 100644 index 0000000..850b019 --- /dev/null +++ b/book/intro/workshop/07.md @@ -0,0 +1,11 @@ +# Exercise 7: Collaborate + +Fork, PR, merge. + +```{admonition} Check your understanding +:class: tip + +Before moving on to the next exercise, make sure you understand the following: +1. What is a fork? +... +``` \ No newline at end of file diff --git a/book/intro/workshop/summary.md b/book/intro/workshop/summary.md new file mode 100644 index 0000000..cc3ec68 --- /dev/null +++ b/book/intro/workshop/summary.md @@ -0,0 +1,21 @@ +# Summary of Workshop: All Exercises + +With the exercises, you did all the steps of our TeachBooks workflow! + +```{figure} ../figures/TeachBooks_flowchart_v04.png +--- +width: 500px +align: center +--- +``` + +Here is how the exercises relate to the workflow. + +| Step No. | Name | Exercise | Description | +| :---: | :---: | :---: | :---: | +| 1 | Get and idea | 4 | Create an issue | +| 2 | Create _your_ version of the book | 4 | Create a branch | +| 3 | Edit the book | 1, 2, 3| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | +| 4 | Check changes online | 1, 2, 3 | Workflows and Actions Summary | +| 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready| +| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks | \ No newline at end of file diff --git a/book/references.bib b/book/references.bib index 3168990..3d87be1 100644 --- a/book/references.bib +++ b/book/references.bib @@ -13,4 +13,11 @@ howpublished = {\url{https://agilescientific.com/blog/2021/2/17/which-open-licence-should-i-choose}}, year = {2021}, note = {[Online; posted 17-February-2021]} +} + +@misc{jason_moore, + title={Learn Multibody Dynamics, SymPy}, + author={Moore, Jason}, + url={https://moorepants.github.io/learn-multibody-dynamics/sympy.html}, + year={2023} } \ No newline at end of file diff --git a/book/workflows/github_dev.md b/book/workflows/github_dev.md index 92933f7..60f8d9d 100644 --- a/book/workflows/github_dev.md +++ b/book/workflows/github_dev.md @@ -5,7 +5,6 @@ ```{figure} figures/Online_VS0.PNG --- -name: New File width: 50% align: center --- @@ -16,7 +15,6 @@ New File ```{figure} figures/Online_VS1.PNG --- -name: VS Code in Browser width: 70% align: center --- @@ -29,7 +27,6 @@ In the bottom left you can see the branch you are working in. ```{figure} figures/Online_VS2.PNG --- -name: GitHub Actions width: 70% align: center --- @@ -39,7 +36,6 @@ You will see the latest commit you just did (in this case text). After the pipel ```{figure} figures/Online_VS3.PNG --- -name: Deployed Branches width: 60% align: center --- diff --git a/book/workflows/stage_commit_push_vscode.md b/book/workflows/stage_commit_push_vscode.md index d917fa9..0bf888e 100644 --- a/book/workflows/stage_commit_push_vscode.md +++ b/book/workflows/stage_commit_push_vscode.md @@ -3,6 +3,8 @@ For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu: ```{figure} ../images/git-new-file.png +--- +width: 100% --- The new file appears in the Source Control menu. @@ -14,6 +16,8 @@ Notice that there is a green letter U placed besides the file, meaning that our Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this: ```{figure} ../images/git-file-added.png +--- +width: 100% --- The new file has been staged, and we've written a Commit Message. @@ -26,6 +30,9 @@ Now, we are ready to add the changes to the repository. This is done by *committ In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: ๐Ÿ”„, highlighted in the image below) to push the changes to GitLab/GitHub. ```{figure} ../images/git-push.png +--- +width: 100% + --- After committing, click the ๐Ÿ”„ button to push our changes to the remote repository. ``` \ No newline at end of file diff --git a/book/workflows/user45_check_changes.md b/book/workflows/user45_check_changes.md index 4b2377c..bd8b79d 100644 --- a/book/workflows/user45_check_changes.md +++ b/book/workflows/user45_check_changes.md @@ -25,7 +25,7 @@ Note: use `--all` for the jupyter-book whenever building a book to make sure the Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following: ```{figure} ../figures/buildbook.PNG ---- + Output ``` Paste the last line into your browser to see the updated changes. diff --git a/requirements.txt b/requirements.txt index a3917fa..ff54450 100644 --- a/requirements.txt +++ b/requirements.txt @@ -11,4 +11,5 @@ sphinx-image-inverter --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple sphinx-thebe ~= 0.9.9 -docutils==0.17.1 \ No newline at end of file +docutils==0.17.1 +sphinx-exercise \ No newline at end of file