diff --git a/.github/workflows/call-deploy-book.yml b/.github/workflows/call-deploy-book.yml new file mode 100644 index 0000000..bec1772 --- /dev/null +++ b/.github/workflows/call-deploy-book.yml @@ -0,0 +1,24 @@ +name: call-deploy-book + +on: + push: + branches: + - '**' + # If your git repository has the Jupyter Book 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. + # + paths: + - book/** + - .github/workflows/call-deploy-book.yml + workflow_dispatch: + +jobs: + call-workflow: + uses: TeachBooks/deploy-book-workflow/.github/workflows/deploy-book.yml@main + secrets: inherit + permissions: + contents: read + pages: write + id-token: write + diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7803c8f --- /dev/null +++ b/.gitignore @@ -0,0 +1,137 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST +.vscode/ + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +.python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# Jupyter Book +_build/ +.teachbooks/ + +# poetry files +pyproject.toml diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..ba74ac9 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,3 @@ +This book is licensed under a Creative Commons Attribution 4.0 International License. + +Creative Commons License \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..47f6bad --- /dev/null +++ b/README.md @@ -0,0 +1,52 @@ +# Your first TeachBook using the GitHub template + + +The template allows you to start your own Jupyter Book and hosting that book online without knowledge on Git, the Jupyter book package, python or anaconda. It doesn't elaborate on the collaborative functionalities of Git or how to edit the book. + +## Features +- A github repository structure for making a [Jupyter Book](https://github.com/executablebooks/jupyter-book) (`/book`) +- An empty book 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`.) +- An example book logo (`/book/figures/TUDelft_logo_rgb.png`, `/book/config.yml`) +- The configuration files set ready to make your Jupyter Notebooks pages work with [live code using our sphinx-thebe extension](https://teachbooks.tudelft.nl/jupyter-book-manual/features/live_code.html) and our recommended settings (`/book/config.yml`) +- An example of setting up preprocessing your table of contents to hide certain draft chapters for eg. students (`_toc.yml`) +- A file containing all the recommended software packages (`requirements.txt`) +- A file containing the recommended license CC BY 4.0 (`LICENSE.md`) +- Our [GitHub workflow for publishing your book to GitHub Pages](https://github.com/TeachBooks/deploy-book-workflow) (`.github/workflow/call-deploy-book.yml`) +- A gitignore file containing standard python filetype to ignore (`.gitignore`) +- A readme containing information how to use the template, which can adjusted after using the template (`README.md`) + +## How to get started + +How to use the template is demonstrated in the figure below, followed by a step-by-step tutorial. + +![template-demo](figures/teachbooks-template.gif) +The demonstration is also available as a video [here](https://youtu.be/nN3Oi_MVvF0). + +1. To get started making your Jupyter Book with our functionalities, use the [template book](https://github.com/TeachBooks/template) as template: + +![use-template](figures/use_template.png) + +2. Fill in a repository name, this name will be used in the future url of your book: + +![create_new_repository](figures/create_new_repository.png) + +3. You need to activate GitHub pages so that your website is published to the internet. As long as you don't do this your book is not published online. Actually, now that you've taken this template our workflow tries to publish it to GitHub pages, which you didn't have the chance to activate yet. That's why you probably received an email with 'call-deploy-book: Some jobs were not successful' and you see the failed job under `Actions` - `All workflows` - `call-deploy-book` - `Initial commit`. You can activate GitHub pages by setting the source for GitHub pages to GitHub Actions under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`: + +![Activate pages](figures/set_up_pages.png) + +4. Make an edit to the book by editing and committing changes to one of the files in the `book/` subdirectory (available under `Code`). Now checkout the progress of the publishing workflow under `Actions` - `All workflows` - `call-deploy-book` -``. Remember, the first commit which is there has failed because GitHub Pages wasn't activated at the time of `Initial commit`, you could also re-run that job if you don't want to make an edit. You can do so by running the workflow from `Actions` - `All workflows` - `call-deploy-book` - `Initial commit` - `Re-run all jobs` - `Re-run jobs`: + +![Action](figures/action_re-run.jpeg) + +5. When the workflow has finished, visit your build book at `https://.github.io/` (case sensitive). For our example it is [https://dummydocent.github.io/test_book_from_template/](https://dummydocent.github.io/test_book_from_template/) for the shown repository. These links are visible in the action's summary as well, as shown in the figure of step 4. + +Additional tip: +Set the repository website as your GitHub Pages website under `Code`- `About` - - `Website` - `Use your GitHub Pages Website` + +![github_pages_as_website](figures/use_github_pages_website.png) \ No newline at end of file diff --git a/book/_config.yml b/book/_config.yml new file mode 100644 index 0000000..23c06d3 --- /dev/null +++ b/book/_config.yml @@ -0,0 +1,34 @@ +title: Template +author: TeachBooks Team from Delft university of Technology, built with TeachBooks and Jupyter Book, CC BY 4.0 #Add your own name here +logo: figures/TUDelft_logo_rgb.png #add your own logo here + +execute: + execute_notebooks: "off" + +only_build_toc_files: true + +html: + favicon : "figures/favicon.ico" + baseurl : "https://teachbooks.github.io/template/" #Replace this with your own URL + home_page_in_navbar : true + +sphinx: + config: + html_js_files: + - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js + thebe_config: + use_thebe_lite: true + exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] + html_theme_options: + repository_url: "https://github.com/TeachBooks/template" #add your own repo URL here + use_repository_button: true + use_issues_button : true + launch_buttons: + thebe: true + html_show_copyright: false + extra_extensions: + - sphinx.ext.imgconverter + - jupyterbook_patches + +bibtex_bibfiles: + - references.bib diff --git a/book/_toc.yml b/book/_toc.yml new file mode 100644 index 0000000..b21c2ce --- /dev/null +++ b/book/_toc.yml @@ -0,0 +1,13 @@ +format: jb-book +root: intro.md + +parts: + - caption: Contents + chapters: + - file: some_content/overview.md +# START REMOVE-FROM-PUBLISH + sections: + - file: some_content/text_and_code.ipynb +# END REMOVE-FROM-PUBLISH + - file: references.md + - file: credits.md diff --git a/book/credits.md b/book/credits.md new file mode 100644 index 0000000..d416615 --- /dev/null +++ b/book/credits.md @@ -0,0 +1,19 @@ +(credits)= +# Credits + +You can refer to this book as: + +> `` `` ``, ``, >. + +You can refer to individual chapters or pages within this book as: + +> `` `` ``. In `<Author>` (Ed.), `<Book Title>`, `<Year>`, <url> + +## Source files +The files are stored on a [public Git repository](<url>). The published version of this book is compiled from branch `<branch>`. View the repository README file or contact the author for additional information. + +(editor)= +## About the Editor +`<Author>` + +### Acknowledgements diff --git a/book/figures/TUDelft_logo_rgb.png b/book/figures/TUDelft_logo_rgb.png new file mode 100644 index 0000000..753f310 Binary files /dev/null and b/book/figures/TUDelft_logo_rgb.png differ diff --git a/book/figures/favicon.ico b/book/figures/favicon.ico new file mode 100644 index 0000000..e8dca93 Binary files /dev/null and b/book/figures/favicon.ico differ diff --git a/book/intro.md b/book/intro.md new file mode 100644 index 0000000..1fcba9c --- /dev/null +++ b/book/intro.md @@ -0,0 +1,12 @@ +(intro)= +# Welcome to the Template Book + +_Write book intro here. This is the first page the student will see when opening the url._ + +This book can be used as a template for other books. It includes all software developed by the CEG interactive books initiative and make it easier to keep various software in those other books up to date. + +--- + +This book is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>. + +<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png"/></a> diff --git a/book/references.bib b/book/references.bib new file mode 100644 index 0000000..658a4ca --- /dev/null +++ b/book/references.bib @@ -0,0 +1,6 @@ +@misc{jason_moore, + title={Learn Multibody Dynamics, SymPy}, + author={Moore, Jason}, + howpublished={\url{https://moorepants.github.io/learn-multibody-dynamics/sympy.html}}, + year={2023} +} \ No newline at end of file diff --git a/book/references.md b/book/references.md new file mode 100644 index 0000000..5fd6c7d --- /dev/null +++ b/book/references.md @@ -0,0 +1,3 @@ +# References +:::{bibliography} +::: diff --git a/book/some_content/overview.md b/book/some_content/overview.md new file mode 100644 index 0000000..5adab4e --- /dev/null +++ b/book/some_content/overview.md @@ -0,0 +1,3 @@ +# Overview + +Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. \ No newline at end of file diff --git a/book/some_content/text_and_code.ipynb b/book/some_content/text_and_code.ipynb new file mode 100644 index 0000000..9abffd6 --- /dev/null +++ b/book/some_content/text_and_code.ipynb @@ -0,0 +1,51 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Text and code\n", + "\n", + "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "hello world\n" + ] + } + ], + "source": [ + "print('hello world')" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "base", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.9.18" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/figures/action_re-run.jpeg b/figures/action_re-run.jpeg new file mode 100644 index 0000000..03f897b Binary files /dev/null and b/figures/action_re-run.jpeg differ diff --git a/figures/create_new_repository.png b/figures/create_new_repository.png new file mode 100644 index 0000000..58b4e5b Binary files /dev/null and b/figures/create_new_repository.png differ diff --git a/figures/set_up_pages.png b/figures/set_up_pages.png new file mode 100644 index 0000000..ee2d57b Binary files /dev/null and b/figures/set_up_pages.png differ diff --git a/figures/teachbooks-template.gif b/figures/teachbooks-template.gif new file mode 100644 index 0000000..50d6156 Binary files /dev/null and b/figures/teachbooks-template.gif differ diff --git a/figures/use_github_pages_website.png b/figures/use_github_pages_website.png new file mode 100644 index 0000000..76a03c3 Binary files /dev/null and b/figures/use_github_pages_website.png differ diff --git a/figures/use_template.png b/figures/use_template.png new file mode 100644 index 0000000..c6d21fb Binary files /dev/null and b/figures/use_template.png differ diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..ebd2a79 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,15 @@ +# first list the packages you wish to download from PyPI +teachbooks # depends on jupyter-book +# numpy + +# docutils version for reference page formatting +docutils==0.17.1 + +# now list the packages (and the respective url) you wish to download from the GitLab package registry +--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/17983/packages/pypi/simple #temporarily disable +jupyterbook_patches ~= 0.1.4 #temporarily disable +--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple #temporarily disable +sphinx-thebe ~= 0.9.9 #temporarily disable + +# lastly any packages you wish to download directly from a Git repository +download_link_replacer @ git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer #temporarily disable