Skip to content
Snippets Groups Projects
Commit 5d84a4c7 authored by Minouk Noordsij's avatar Minouk Noordsij
Browse files

Update manual for publication

parent daef4aba
No related branches found
No related tags found
1 merge request!8Update manual for publication
Hide whitespace changes
Inline Side-by-side
Showing
with 30 additions and 1205 deletions
_toc.yml
+ 5
− 5
View file @ 5d84a4c7
......@@ -3,25 +3,25 @@
format: jb-book
root: content/intro.md
parts:
- caption: Building your first book
numbered: true
chapters:
- file: content/first_book/installations/installations.md
sections:
- file: content/first_book/installations/conda.md
- file: content/first_book/installations/git.md
- file: content/first_book/installations/VSCode.md
- file: content/first_book/installations/jupyterbooks.md
- file: content/first_book/building.md
- file: content/first_book/publish.md
- caption: Additional information
numbered: true
chapters:
- file: content/additional/template.md
- file: content/additional/conversion.md
- file: content/additional/config.md
- file: content/additional/transaltion_guide.md
- file: content/additional/translation.md
- file: content/additional/links.md
- file: content/additional/contact.md
- file: content/additional/credits.md
- file: content/additional/fig_animation.md
\ No newline at end of file
content/Archive/basics/anatomy/anatomy.md deleted 100644 → 0
+ 0
− 24
View file @ daef4aba
# Anatomy of a Jupyter Book
There are three things that you need in order to build a Jupyter Book, each of which is already part of the TU Delft template that you have downloaded before:
- A configuration file (`_config.yml`)
- A Table of Contents (`_toc.yml`)
- Your book's content
```console
$ tree template-book
template-book/
├── content
├── images
├── _config.yml
├── _toc.yml
├── intro.md
├── references.bib
└── requirements.txt
```
These sections describe the content of the basic files of a Jupyter Book.
```{tableofcontents}
```
content/Archive/basics/anatomy/config.md deleted 100644 → 0
+ 0
− 312
View file @ daef4aba
# Configuration File
You can configure Jupyter Book with a **YAML configuration file (`_config.yml`)**.
This file controls a number of options and feature flags.
This page is a reference for the `_config.yml` structure TU Delft implementation uses and what have to be changed when creating a new book.
```{caution}
YAML can be tricky when it comes to how it treats certain kinds of values. For example, when using strings in YAML it is usually fine to omit quotes around them. However, there are certain values that will be *converted* to boolean values if they do not have strings around them. For example, `false`, `true`, `off`, etc. In addition, pure numbers will be converted to `float` or `int` unless you put strings around them.
```
## Configuration defaults
Below is the full default configuration file for the TU Delft implementation.
```{note}
The TU Delft template provides default settings for creating a new book, and it is advisable to only modify the necessary ones. These parameters are marked with an `asterisk (*)` in the following list and with the phrase `Change this parameter` in the `_config.yml` file for easy reference.
```
## Book Settings
All the basic information regarding the book.
```yaml
#######################################################################################
# Book Settings
title: "\"How-To\" Manual"
author: Theodosios Athanasakis
description: Manual for all the professors that want to publish their books with Jupyter books implementation.
copyright: Delft University of Technology, CC BY-SA 4.0
logo: content/images/tudelft.png
exclude_patterns: [ _build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints" ]
only_build_toc_files: true
```
`title*`
: The title of the book. Will be placed in the left navbar.
`author*`
: The author of the book.
`description*`
: Text to indicate what the book is about.
`copyright`
: Copyright tag to be placed in the footer.
`logo`
: A path to the book logo.
`exclude_patterns`
: Patterns to skip when building the book. Any files that match the patterns described there will be excluded from the build.
`only_build_toc_files`
: Auto-exclude files not in the ToC and avoid building README, etc.
## Execution Settings
**No need to change anything.**
```{seealso}
See more information: [Execute and cache your pages](https://jupyterbook.org/content/execute.html).
```
```yaml
#######################################################################################
# Execution Settings
execute:
execute_notebooks: force
cache: ""
exclude_patterns: [ ]
timeout: 30
run_in_temp: false
allow_errors: false
stderr_output: show
```
`execute_notebooks`
: Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off").
`cache`
: A path to the jupyter cache that will be used to store execution artifacts. Defaults to `_build/.jupyter_cache/`.
`exclude_patterns`
: A list of patterns to *skip* in execution (e.g. a notebook that takes a really long time).
`timeout`
: The maximum time (in seconds) each notebook cell is allowed to run.
`run_in_temp`
: If `True`, then a temporary directory will be created and used as the command working directory (cwd), otherwise the notebook's parent directory will be the cwd.
`allow_errors`
: If `False`, when a code cell raises an error, the execution is stopped; otherwise all cells are always run.
`stderr_output`
: One of 'show', 'remove', 'remove-warn', 'warn', 'error', 'severe'.
## Parse and Render Settings
**No need to change anything.**
```{seealso}
See more information: [Syntax Extensions](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html).
```
```yaml
#######################################################################################
# Parse and Render Settings
parse:
myst_enable_extensions:
- amsmath
- colon_fence # To allow for ::: instead of ``` blocks.
- deflist
- dollarmath
- html_admonition
- html_image
- linkify
- replacements
- smartquotes
- substitution
- tasklist
myst_url_schemes: [ mailto, http, https ]
myst_dmath_double_inline: true
```
`myst_enable_extensions`
: Extra plugins of MyST for more capabilities.
`myst_url_schemes`
: URI schemes that will be recognised as external URLs in Markdown links.
`myst_dmath_double_inline`
: Allow display math ($$) within an inline context.
## HTML-Specific Settings
```yaml
#######################################################################################
# HTML-Specific Settings
html:
favicon: "content/images/favicon.ico"
use_edit_page_button: true
use_repository_button: true
use_issues_button: false
use_multitoc_numbering: true
extra_navbar: Powered by <a href="https://www.tudelft.nl/">TU Delft</a>
extra_footer: ""
google_analytics_id: ""
home_page_in_navbar: true
baseurl: ""
comments:
hypothesis: true
utterances: false
announcement: "Under Development"
```
`favicon`
: A path to a favicon image
`use_edit_page_button`
: Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in.
`use_repository_button`
: Whether to add a link to your repository button.
`use_issues_button`
: Whether to add an "open an issue" button
`use_multitoc_numbering`
: Continuous numbering across parts/chapters.
`extra_navbar*`
: It will be displayed underneath the left navbar (**optional**).
`extra_footer*`
: It will be displayed underneath the footer (**optional**).
`google_analytics_id`
: A Google Analytics (GA) id that can be used to track book views.
`home_page_in_navbar`
: Whether to include your home page in the left Navigation Bar.
`baseurl`
: The base URL where your book will be hosted. Used for creating image previews and social links.
`hypothesis`
: Hypothesis for comments.
`utterances`
: Utterances for comments.
`announcement*`
: A banner announcement at the top of the site (**optional**).
## LaTeX-Specific Settings
Define the name of the latex output file for PDF builds.
```yaml
#######################################################################################
# LaTeX-Specific Settings
latex:
latex_engine: pdflatex
use_jupyterbook_latex: true
latex_documents:
targetname: book.tex
```
`latex_engine`
: One of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'.
`use_jupyterbook_latex`
: Use sphinx-jupyterbook-latex for pdf builds as default.
`targetname*`
: Name of the produced book from PDF build (**optional**).
## Launch Button Settings
**Do not change these parameters.**
```yaml
#######################################################################################
# Launch Button Settings
launch_buttons:
notebook_interface : classic
```
`notebook_interface`
: The interface interactive links will activate ["classic", "jupyterlab"].
## Information about where the book exists on the web
```yaml
#######################################################################################
# Information about where the book exists on the web
repository:
url: https://gitlab.tudelft.nl/opentextbooks/how-to-manual/
path_to_book: ""
branch: master
```
`url*`
: Online location of your book.
`path_to_book*`
: A path to your book's folder, relative to the repository root (**optional**).
`branch*`
: Which branch of the repository should be used when creating links (**optional**).
## References
**Do not change these parameters.**
```yaml
#######################################################################################
# Add a bibtex file so that we can create citations
bibtex_bibfiles:
- references.bib
```
`bibtex_bibfiles`
: File with all the citations used in the book.
## Advanced and power-user settings
**Do not change these parameters.**
```yaml
#######################################################################################
# Advanced and power-user settings
sphinx:
extra_extensions: [...]
local_extensions: [...]
recursive_update: false
config: [...]
```
`extra_extensions`
: A list of extra extensions to load by Sphinx (added to those already used by JB).
`local_extensions`
: A list of local extensions to load by sphinx specified by "name: path" items.
`recursive_update`
: A boolean indicating whether to overwrite the Sphinx config (true) or recursively update (false).
`config`
: key-value pairs to directly over-ride the Sphinx configuration.
## More Information
Find more information about `_config.yml`:
- [Configuration reference](https://jupyterbook.org/en/stable/customize/config.html)
- [Syntax Extensions](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html)
- [Execute and cache your pages](https://jupyterbook.org/content/execute.html)
- [Math and equations/Latex-style math](https://jupyterbook.org/en/stable/content/math.html#latex-style-math)
content/Archive/basics/anatomy/content.md deleted 100644 → 0
+ 0
− 52
View file @ daef4aba
# Content
The potential of Jupyter Books is limitless. This page includes useful links to the most important features that this implementation of Jupyter Books can showcase through its various plugins. However, it's recommended to also read the complete official documentation in order to gain a comprehensive understanding of the capabilities at your disposal.
By exploring the official and other documentation, you can unleash the full potential of Jupyter Books and create engaging and informative content that will capture your readers' attention and leave a lasting impression.
## Official Documentation
- [Official Documentation](https://jupyterbook.org/)
- [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) - **Refer to this for quick reference**
## General Structure
- [How headers and sections map onto to book structure](https://jupyterbook.org/en/stable/structure/sections-headers.html)
- [Special content blocks](https://jupyterbook.org/en/stable/content/content-blocks.html)
- [Components and UI elements](https://jupyterbook.org/en/stable/content/components.html)
- [Hide or remove content](https://jupyterbook.org/en/stable/interactive/hiding.html)
- [Control the page layout](https://jupyterbook.org/en/stable/content/layout.html)
## References / Citations
- [Get started with references](https://jupyterbook.org/en/stable/tutorials/references.html)
- [References and cross-references](https://jupyterbook.org/en/stable/content/references.html)
- [Citations and bibliographies](https://jupyterbook.org/en/stable/content/citations.html)
## Math
- [Math and equations](https://jupyterbook.org/en/stable/content/math.html)
- [Proofs, Theorems, and Algorithms](https://jupyterbook.org/en/stable/content/proof.html)
- [Sphinx-proof Documentation](https://sphinx-proof.readthedocs.io/en/latest/)
- [SciPy documentation](https://docs.scipy.org/doc/scipy/)
- [NumPy documentation](https://numpy.org/doc/1.24/)
## Figures
- [Images and figures](https://jupyterbook.org/en/stable/content/figures.html)
- [Interactive data visualizations](https://jupyterbook.org/en/stable/interactive/interactive.html)
## Plots / Graphs
- [Matplotlib: Visualization with Python](https://matplotlib.org/)
- [Plotly Open Source Graphing Library for Python](https://plotly.com/python/)
## Comments
- [Commenting and annotating](https://jupyterbook.org/en/stable/interactive/comments.html)
- [Hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)
- [Hypothesis (Official Website)](https://web.hypothes.is/)
- [Announcement banners](https://jupyterbook.org/en/stable/web/announcements.html)
## Exercises
- [Sphinx-exercise Documentation](https://ebp-sphinx-exercise.readthedocs.io/en/latest/)
- [JupyterQuiz GitHub](https://github.com/jmshea/jupyterquiz)
content/Archive/basics/anatomy/requirements.md deleted 100644 → 0
+ 0
− 31
View file @ daef4aba
# Requirements
In Python, and as a consequence Jupyter Books, a requirements.txt file is a type of file that usually stores information about all the libraries, modules, and packages in itself that are used while developing a particular project.
At this point, the `requirements.txt` consists of the following packages:
```text
numpy
scipy
matplotlib
plotly
myst_nb
jupyterquiz
sphinx-exercise
sphinx-proof
jupyter-book
```
To install the required packages for your book, you can simply run:
```bash
pip install -r requirements.txt
```
## More Information
Find more information on how to set up your working environment:
- [](build:create-env)
content/Archive/basics/anatomy/toc.md deleted 100644 → 0
+ 0
− 66
View file @ daef4aba
# Table of Contents
Your book's structure is determined by a **Table of Contents**. This is a YAML file (called `_toc.yml`) that defines a structure that Jupyter Book uses to create the order and nesting of pages.
## Structure of a Book
The table of contents is broadly organized like so:
```yaml
format: jb-book
root: index
parts:
- caption: Name of Part 1
chapters:
- file: path/to/part1/chapter1
- file: path/to/part1/chapter2
sections:
- file: path/to/part1/chapter2/section1
- caption: Name of Part 2
chapters:
- file: path/to/part2/chapter1
- file: path/to/part2/chapter2
sections:
- file: path/to/part2/chapter2/section1
- chapters:
- file: path/to/chapter1
- url: https://example.com
title: Example website
- glob: sub-folder/other*
```
Here is a brief explanation of each key:
`format:`
: Defines the structure of this Table of Contents (e.g., how to interpret the key names). `jb-book` tells Jupyter Book to expect `chapters` and `parts` terminology (see below for details).
`root:`
: The first page of your book (aka, the "root page"). It is the landing page for the HTML of your book. All paths for chapters/sections will be relative to this root document.
`parts:`
: A list of entries, each of which defines a chapter.
This is useful if you'd like to use different groups of chapters.
`chapters:`
: A list of entries, each of which maps onto **chapters** of your book.
`sections:`
: A list of entries that define **subsections** of a chapter. This is useful if you'd like to split a chapter across multiple pages (each making up a **section** of the chapter). See [How headers and sections map onto to book structure](https://jupyterbook.org/en/stable/structure/sections-headers.html) for more information.
`file:`
: A path that points to a local text file, which contains the content of this entry (the chapter, section, or sub-section). These paths should be relative to your `_toc.yml` file.
`glob:`
: A [glob-like pattern](https://docs.python.org/3/library/glob.html) that can be used to match against **multiple local files**. Each of these files will be collected and inserted into your content, in the order that `glob` discovers them.
`url:`
: An external link to a website (starting with `http` or `https`). This will be inserted into your book's Table of Contents, though it will not affect your book's structure (like numbering). When a `title:` entry is provided its text is used instead of the full URL.
## More Information
Find more information about `_toc.yml`:
- [Structure the Table of Contents](https://jupyterbook.org/en/stable/structure/toc.html)
- [Configure the Table of Contents](https://jupyterbook.org/en/stable/structure/configure.html)
- [How headers and sections map onto to book structure](https://jupyterbook.org/en/stable/structure/sections-headers.html)
content/Archive/basics/coc.md deleted 100644 → 0
+ 0
− 6
View file @ daef4aba
# Code of Conduct
```{admonition} Under Development
:class: warning, dropdown
This feature is still under development, and we are actively working on making it available as soon as possible. For more updates, please [contact the responsible department](contact.md).
```
content/Archive/basics/contact.md deleted 100644 → 0
+ 0
− 13
View file @ daef4aba
# Contact
This page is designed to provide you with the means to get in touch with us if you have any questions or feedback about the "How-To" manual. We understand that learning and using new technologies can be challenging, and we want to make sure that we are here to support you every step of the way.
Whether you have a question about a particular chapter or section of the manual, or you simply want to share your thoughts on your experience with Jupyter Books, we would love to hear from you. Our team is dedicated to making this manual as helpful and user-friendly as possible, and your input is crucial to achieving that goal.
So, please feel free to reach out to us using any of the contact methods listed on this page. We value your feedback and look forward to hearing from you.
```{admonition} Under Development
:class: warning, dropdown
This feature is still under development, and we are actively working on making it available as soon as possible. For more updates, please contact the responsible department.
```
content/Archive/basics/conversion.md deleted 100644 → 0
+ 0
− 22
View file @ daef4aba
# Conversion of existing files
If you have a book that is already written in LaTeX or Microsoft Word format, it is straightforward to convert it into a Jupyter Book with TU Delft's specialized tools. The conversion process is made easier with only some click.
## LaTeX to Jupyter Book
You can convert a LaTeX project into a Jupyter project by:
```{admonition} Under Development
:class: warning, dropdown
This feature is still under development, and we are actively working on making it available as soon as possible. For more updates, please [contact the responsible department](contact.md).
```
## Word to Jupyter Book
You can convert a Microsoft Word file into a Jupyter project by:
```{admonition} Under Development
:class: warning, dropdown
This feature is still under development, and we are actively working on making it available as soon as possible. For more updates, please [contact the responsible department](contact.md).
```
\ No newline at end of file
content/Archive/basics/next.md deleted 100644 → 0
+ 0
− 7
View file @ daef4aba
# And now what?
Congratulations! You have reached the end of this "How-To" manual, and we trust that it has equipped you with the necessary knowledge and skills to create a compelling Jupyter Book for TU Delft repository. We hope this manual has been helpful and informative, and that you now feel confident to dive in and create your own interactive book.
We understand that creating an interactive book can be a challenging task, but we believe that the effort you put into it will be well worth it. Remember, the journey of a thousand miles begins with a single step, and we encourage you to take that first step and start creating your Jupyter Book today.
If you still have any questions or need further assistance, don't hesitate to [contact the responsible department](contact.md). We are always here to help and support you throughout your journey. Thank you for choosing the Jupyter Books for your interactive book, and we wish you all the best in your future endeavors as you embark on creating interactive books that engage and inspire your readers.
content/Archive/basics/process/build.md deleted 100644 → 0
+ 0
− 124
View file @ daef4aba
# Build your book
Once you've added content and configured your book, it's time to build outputs for your book. We'll use the `jupyter-book build` command line tool for this.
Currently, there are two kinds of supported outputs: an HTML website for your book, and a PDF that contains all the pages of your book that is built from the book HTML. In this tutorial, we'll focus on building HTML outputs. See [Build a PDF](https://jupyterbook.org/en/stable/advanced/pdf.html) to find more on building a PDF.
## Prerequisites
In order to build the HTML for each page, you should have followed the steps in [](overview.md) and [](create.md). You should have a collection of notebook/Markdown files in your `<book-path>` folder, a `_toc.yml` file that defines the structure of your book, and any configuration you'd like in the `_config.yml` file.
```{note}
The TU Delft template has all the necessary configurations and files. You have to adjust the content and the `_toc.yml` files to your individual work. Follow the instruction at the [](../anatomy/anatomy.md) for further information about all the files of you book.
```
(build:create-env)=
## Create environment
In order to build your books, you have to create a closed environment for the necessary packages to be downloaded. There are several ways to achieve that. For the purpose of this tutorial, we will use a Conda environment.
```{note}
You can create more than one environments with different names. However, the inplementation of TU Delft follows one specific `requirement.txt` file and as a concequence `environment`. Thus, it is not necessary to create multiple environments.
```
First, navigate your command line to the root path of the book. Then, you can create and activate an environment by running the following commands (preferably one by one):
```bash
conda create --name=<env-name> python=3.7
conda activate <env-name>
conda install pip
pip install -r requirements.txt
```
In principle, the previous command will create and activate the environment. If something goes wrong, check on the internet for the error messages, or (if you cannot find a solution) [contact the responsible department](../contact.md) of TU Delft.
:::{admonition} Delete environment
:class: seealso, dropdown
If you want to remove an environment, run the following command:
```bash
conda remove --name <env-name> --all
```
:::
## Active environment
Every time you want to build your build again, make sure you have the right environment activated by running the following command:
```bash
conda activate env-name
```
:::{admonition} Deactivate environment
:class: seealso, dropdown
If you want to deactivate an environment, run the following command:
```bash
conda deactivate <env-name>
```
:::
## Build your book's HTML
Now that your book's content is in your book folder, you've defined your book's structure in `_toc.yml`, and you have built the right environment, you can build the HTML for your book.
Do so by running the following command:
```bash
jupyter-book build <book-path>
```
This will generate a fully-functioning HTML site using a **static site generator**. The site will be placed in the `_build/html` folder, something like this:
```bash
book-path
└──_build
└── html
├── _images
├── _static
├── index.html
├── intro.html
...
```
These are the static files for a standalone website! They contain the HTML and all assets needed to view your book in a browser.
You can open the pages in the site by navigating to that folder and opening the `html` files with your web browser.
```{note}
You can also use the short-hand `jb` for `jupyter-book`. E.g.,: `jb build <book-path>`.
```
## Page Cacheing
By default, Jupyter Book will only build the HTML for pages that have been updated since the last time you built the book.
If you'd like to force Jupyter Book to re-build a particular page, you can either edit the corresponding file in your book's folder, or delete that page's HTML in the `_build/html` folder.
You can also signal a full re-build using the `--all` option:
```bash
jupyter-book build --all <book-path>
```
## Preview your built HTML
To preview your book, you can open the generated HTML files in your browser. Either double-click the html file in your local folder, or enter the absolute path to the file in your browser navigation bar adding `file://` at the beginning (e.g. `file://<book-path>/_build/index.html`).
Take a look at the web page that was generated from the markdown page that you created. Note how the links you inserted were automatically **resolved** to point to the right place. This is how you can keep consistent pointers from one section of your book to another.
## More Information
Find more information about building your book:
- [Build your book](https://jupyterbook.org/en/stable/start/build.html)
- [Conda Install Requirements](https://linuxhint.com/conda-install-requirements-txt/)
- [PIP](https://pip.pypa.io/en/stable/)
- [Build a PDF](https://jupyterbook.org/en/stable/advanced/pdf.html)
content/Archive/basics/process/create.md deleted 100644 → 0
+ 0
− 85
View file @ daef4aba
# Create your book
Now that you set up the environment of your books, it is time to create a book.
## Download the TU Delft template
TU Delft has developed a template book to start with and update it with your content. Download this template by:
```{admonition} Under Development
:class: warning, dropdown
This feature is still under development, and we are actively working on making it available as soon as possible. For more updates, please [contact the responsible department](../contact.md).
```
## Anatomy of a Jupyter Book
There are three things that you need in order to build a Jupyter Book, each of which is already part of the TU Delft template that you have downloaded before:
- A configuration file (`_config.yml`)
- A Table of Contents (`_toc.yml`)
- Your book's content
For example, take a look at the template book that you just downloaded:
```console
$ tree template-book
template-book/
├── content
├── images
├── _config.yml
├── _toc.yml
├── intro.md
├── references.bib
└── requirements.txt
```
There are a few extra files in there that we include to show off some new features, but the **required** pieces are `_toc.yml`, `_config.yml`, and content files. You can find more information at [](../anatomy/anatomy.md).
We’ll cover each briefly below, and you can find more information about them elsewhere in this documentation.
## Book configuration (`_config.yml`)
The configuration for your book is in a YAML file called `_config.yml`.
You can define metadata for your book (such as its title), add a book logo, turn on different "interactive" buttons, and more.
```{admonition} More about _config.yml?
:class: seealso, dropdown
For more information about your book's configuration file, see [](../anatomy/config.md).
```
## Table of Contents (`_toc.yml`)
Jupyter Book uses your Table of Contents to define the structure of your book. For example, your chapters, sub-chapters, etc.
This is a YAML file with a collection of pages, each one linking to a file in your book.
```{admonition} More about _toc.yml?
:class: seealso, dropdown
For more information about your book's Tale of Contents file, see [](../anatomy/toc.md).
```
## Book content
A collection of text files make up your book's content. These can be one of several types of files, such as markdown (`.md`), Jupyter Notebooks (`.ipynb`) or reStructuredText (`.rst`) files (see [Types of content source files](https://jupyterbook.org/en/stable/file-types/index.html) for a full list).
Some of the most common file types are the three files listed below:
- a **Markdown** file (`markdown.md`)
- a **Jupyter Notebook** (`notebooks.ipynb`)
- a **MyST Markdown Notebook** (`markdown-notebooks.md`)
This Jupyter Book is written entirely in Markdown files. However, you can use whichever type you feel conformable with.
```{warning}
All the packages of this book are tested for Markdown files. If you want to use other type of files, make sure that everything works before you publish it to the TU Delft webpage.
```
## More Information
Find more information about creating your book:
- [Create a template book](https://jupyterbook.org/en/stable/start/create.html)
- [Types of content source files](https://jupyterbook.org/en/stable/file-types/index.html)
content/Archive/basics/process/first-book.md deleted 100644 → 0
+ 0
− 12
View file @ daef4aba
# Create your first book
In this manual, we’ll cover the basics of the Jupyter Book ecosystem, and step you through creating, building, and publishing your first book to the TU Delft webpage.
```{admonition} What you should already know
In order to complete this manual, you should be relatively familiar with using the command line, as well as using a text editor.
```
See the sections of this manual to the left to get started!
```{tableofcontents}
```
content/Archive/basics/process/in-a-nutshell.md deleted 100644 → 0
+ 0
− 62
View file @ daef4aba
# In a Nutshell
After reading all the steps, it is time to summarize everything for faster code snippet searching.
1. Download the TU Delft template
```{admonition} Under Development
:class: warning, dropdown
This feature is still under development, and we are actively working on making it available as soon as possible. For more updates, please [contact the responsible department](../contact.md).
```
2. Create the environment
```bash
conda create --name=<env-name> python=3.7
conda activate <env-name>
conda install pip
pip install -r requirements.txt
```
3. Build your book
```bash
jupyter-book build --all <book-path>
```
4. Create and configure Git
```bash
git init
git add .
git commit -m "first commit"
git remote add origin git@gitlab.com:username/projectpath.git
git push origin master
```
5. Pull, commit, and push new content
```bash
git pull origin master
git add .
git commit -m "commit message"
git push origin master
```
6. Publish your book
```bash
git checkout --orphan <book-version-branch>
git reset
git add _build/html/*
git commit -m "New book version <book-version>"
git push origin <page-version-branch> --force
git update-ref -d HEAD
git reset
git checkout main --force
```
7. Email to TU Delft
- Email: ?????????
- Subject: "?????????"
- Provide link to previous version (If you are uploading a newer version)
content/Archive/basics/process/install.md deleted 100644 → 0
+ 0
− 84
View file @ daef4aba
# Install the environment
In order to create and work on your Jupyter Book, you need to download some programs. Please, find below all the required programs
## Install Conda
You can download and install Conda via [`Miniconda`](https://docs.conda.io/en/latest/miniconda.html). If you do not have already a Python version in your computer, it is better to search the section at the page that includes the latest Python version.
```{admonition} A note for Windows users
:class: warning
Jupyter Book is now also tested against Windows OS! However, there is a known incompatibility for notebook execution when using Python 3.8.
If you use Windows OS, please, download the Python 3.7 version.
```
```{admonition} Miniconda VS Anaconda
:class: dropdown
If you want a better experience while installing more packages, you can download [`Anaconda`](https://www.anaconda.com/) which offers a graphical environment for the handling of the packages.
```
```{admonition} 'Conda' is not recognized
:class: seealso, dropdown
It is suggested to select to add conda to the PATH while installing either Miniconda or Anaconda.
However, if you still get the error message follow the instructions at: ['Conda' is not recognized as internal or external command](https://stackoverflow.com/questions/44515769/conda-is-not-recognized-as-internal-or-external-command).
```
```{admonition} Terminal Emulator
:class: seealso, dropdown
If you are using `Dataspell`, it is suggested to use `Microsoft's Command Prompt` (for Windows only) or `Anaconda Prompt`.
Find more at: [Terminal emulator](https://www.jetbrains.com/help/dataspell/terminal-emulator.html)
```
## Install Git
You can install Git via [Git](https://git-scm.com/downloads). It is necessary in order to execute commands and connect to the GitLab repository.
```{admonition} 'Git' is not recognized
:class: seealso, dropdown
If you get the error message while trying to execute a command, follow the instructions at: [Error "'git' is not recognized as an internal or external command"](https://stackoverflow.com/questions/4492979/error-git-is-not-recognized-as-an-internal-or-external-command).
```
## Install Jupyter Book
You can install Jupyter Book via [`pip`](https://pip.pypa.io/en/stable/):
```bash
pip install -U jupyter-book
```
This will install everything you need to build a Jupyter Book locally.
```{admonition} Install Globally or inside Environment?
:class: tip, dropdown
It is suggested to download Jupyter Book package in the base configuration of Conda. However, if you want to download it only for a specific environment, first create and activate one.
Find more about environments at: [](build:create-env)
```
## Install DataSpell (Optional but also a requirement)
You can install DataSpell via [`DataSpell`](https://www.jetbrains.com/dataspell/). JetBrains DataSpell is an Integrated Development Environment (IDE) for data science with intelligent Jupyter notebooks, interactive Python scripts, and lots of other built-in tools. You can use also other IDEs, such as [VSCode](https://code.visualstudio.com/).
It is very useful to have an editor with all the build-in tools for Jupyter Book development.
## More Information
Find more information about creating your book:
- [Install Jupyter Book](https://jupyterbook.org/en/stable/start/overview.html)
- [Anaconda](https://www.anaconda.com/)
- [Miniconda](https://docs.conda.io/en/latest/miniconda.html)
- ['Conda' is not recognized as internal or external command](https://stackoverflow.com/questions/44515769/conda-is-not-recognized-as-internal-or-external-command)
- [Git](https://git-scm.com/downloads)
- [Error "'git' is not recognized as an internal or external command"](https://stackoverflow.com/questions/4492979/error-git-is-not-recognized-as-an-internal-or-external-command)
- [DataSpell](https://www.jetbrains.com/dataspell/)
- [Terminal emulator](https://www.jetbrains.com/help/dataspell/terminal-emulator.html)
- [VSCode](https://code.visualstudio.com/)
content/Archive/basics/process/overview.md deleted 100644 → 0
+ 0
− 48
View file @ daef4aba
---
jupytext:
formats: md:myst
text_representation:
extension: .md
format_name: myst
format_version: 0.12
jupytext_version: 1.6.0
kernelspec:
display_name: Python 3
language: python
name: python3
---
# Overview
This is a short overview of the major steps in building a Jupyter Book. See the other pages in this guide for more in-depth information.
## The book building process
Building a Jupyter Book broadly consists of these steps:
1. **Create your book's content**. You structure your book with a collection of folders, files, and configuration. See [](create.md).
2. **Build your book**. Using Jupyter Book's command-line interface you can convert your pages into either an HTML or a PDF book. See [](build.md).
3. **Publish your book online**. Once your book is built, you can share it with others. Most common is to build HTML, and host it as a public website. See [](publish.md).
## The Jupyter Book command-line interface
Jupyter Book uses a command-line interface to perform a variety of actions. For example, building and cleaning books. You can run the following command to see what options are at your control:
```{margin}
You can also use the short-hand `jb` for `jupyter-book`. E.g.,:
`jb create mybookname`. We'll use `jupyter-book` for the rest of this manual.
```
```bash
jupyter-book --help
```
% (Problem with jupyter-book commands)
% ```{code-cell}
% (:tags: [remove-input]
% !jupyter-book --help
% ```
Now that we've got what you need, let's get started building your first book.
content/Archive/basics/process/publish.md deleted 100644 → 0
+ 0
− 134
View file @ daef4aba
# Publish your book online
Once you've built the HTML for your book, you can host it online. In this manual, we'll cover how to publish your book online in TU Delft GitLab and make it public for everyone for free.
In order to publish your book at the TU Delft webpage, you have first to create a repository to TU Delft GitLab, upload the necessary content and finally, communicate your request with the responsible department. Below, you can find all the required steps in detail.
## Working with git
### Version control
Git is a method for what software developers call version control, allowing you to efficiently store and share versions of your code (or whichever thing you're working on) and to collaborate on projects, with an easy way of integrating changes. Rather than making new copies of a document anytime you add changes (a very common practice among scientists writing papers alas), the git software keeps track only of the changes in your document, allowing you to step back however far you wish, and comparing versions - both with changes you made, and with changes made by collaborators. The 'undo' option in many other software packages do the same thing. Very likely you've unwittingly already worked with versions of git, for example when writing on Overleaf.
### GitLab
TU Delft hosts a local server with GitLab software, which is an implementation of git with a lot of useful extensions. Anyone with a TU Delft NetID can get a GitLab account, simply by logging in on <https://gitlab.tudelft.nl>. You can then be added to projects or start your own.
The easiest way to work on a project on GitLab with version control is to use an integrated environment in an Integrated Development Environment (IDE), such as DataSpell that we discovered in [](install.md). The website of DataSpell contains detailed instructions. Many people find it easiest to start an empty project on GitLab, then link it (with the provided key) in their IDE; you can then simply add files to the project folder, which the IDE will sync for you with your GitLab repository. If you have never used git, there are a few setup steps; plenty of online tutorials will guide you through them.
## Upload a project from a local file system to GitLab
Source: [Stackoverflow: How to upload project from local file system to GitLab](https://stackoverflow.com/questions/70038069/how-to-upload-project-from-local-file-system-to-gitlab)
NB: This is a hands-on instruction for use on a terminal. No need to do any of this if you integrate with an IDE.
1. You have to create a new repository. Use the following command to create a Git repository. It can be used to convert an existing, non-versioned project to a Git repository or initialize a new, empty repository. A .git folder is created in your directory. This folder contains Git records and configuration files. **You should not edit these files directly.**
```{code}
git init
```
2. If you want to add the files to track with git then you need to use `git add` command. if you want to add new or modified or deleted files in the current directory. then add `.` to select all the files.
```{code}
git add .
```
3. `git commit` creates a snapshot of the changes made to a Git repository which can then be pushed to the main repository. The `-m` option of the commit command lets you write the commit message.
```{code}
git commit -m "first commit"
```
4. You add a “remote” to tell Git which remote repository in GitLab is tied to the specific local folder on your computer. The remote tells Git where to push or pull from. You have to create a project to hold your files. **You should create a project in GitLab. This path should be given in the following command.**
```{code}
git remote add origin git@gitlab.com:username/projectpath.git
```
5. Get the changes from the remote with `git pull`.
```{code}
git pull origin master
```
6. `Push` the commits to the GitLab project.
```{code}
git push origin master
```
7. If any problem occurs in pushing use the following command for `force` push.
```{code}
git push --force origin master
```
(publish:gitlab)=
## Publish your book online to GitLab
We have just pushed the *source files* for our book into our GitLab repository. This makes it publicly accessible for you or others to see.
:::{admonition} Read this before publish anything!
:class: warning
Before performing the below steps, ensure that HTML has been built for each page of your book. There should be a collection of HTML files in your book's `_build/html` folder.
Also, make sure that you have already committed and pushed your book and everything works perfectly. Otherwise, review your work again, and try publishing later.
Lastly, make sure that your command line is at the base path of the project.
If you haven't followed all the previous procedure, the following commands may not work, and you may lose uncommitted work!
```{admonition} I have uncommitted work but I don't want to commit, yet. What can I do?
:class: seealso, dropdown
You can use the command `git stash` which "saves" your work at the current state before running the commands for publishing. After publishing, run `git stash apply` to return to your work!
Find more about `git stash` at: [Git Stash](https://git-scm.com/docs/git-stash)
```
:::
Now, it is time to publish the *build artifact* of your book online, so that it is rendered as a website. For this reason, we have the following sequence of commands. There is no need to understand each step, but pay attention and change the text in `<>` as mentioned.
```bash
git checkout --orphan <book-version-branch>
git reset
git add _build/html/*
git commit -m "New book version <book-version>"
git push origin <page-version-branch> --force
git update-ref -d HEAD
git reset
git checkout main --force
```
```{admonition} This is a non-reversible step!
:class: warning
**Pay attention to the name of the branch that you will use!** `<book-version-branch>` whould be different than your main branch (usually 'master' or 'main') or any other working branch you use. Otherwise, you may lose all the activity of that branch including your files.
```
```{admonition} Book versions
:class: tip, dropdown
If you want to separate the book in versions every time you publish your book, you can state the current version in the branch name (`<book-version-branch>`) and at the commit message (`<version>`)!
```
To update your html files, make changes to your book's content on the working branch of your repository, re-build your book with `jupyter-book build --all <book-path>` and then apply the same procedure with or without a different version name.
## Communicate with TU Delft
To ensure that your book appears on the central page of open books at TU Delft, it is necessary to notify the responsible department of any changes made. To do so, simply email ???????????????? with the subject line "?????????????????" and include a link to the book each time you upload a new version. If you are uploading a newer version, please also provide the link to the previous version so that it can be updated accordingly. If you are not using book versions, simply provide the link once, and it will be automatically updated every time you make changes.
```{admonition} Only complete books
:class: warning
Moreover, if you are not using version control for your book, please ensure that your book is complete before proceeding to the previous step ([](publish:gitlab)). This is important because your public book will be automatically updated with new content, and incomplete versions may be removed when identified.
```
## More Information
Find more information about creating your book:
- [DataSpell](https://www.jetbrains.com/dataspell/)
- [Stackoverflow: How to upload project from local file system to GitLab](https://stackoverflow.com/questions/70038069/how-to-upload-project-from-local-file-system-to-gitlab)
- [Git Stash](https://git-scm.com/docs/git-stash)
content/additional/conversion.md
+ 17
− 15
View file @ 5d84a4c7
<!-- #region -->
# Conversion of existing files
# Conversion from Word or LaTeX
If you have a book that is already written in LaTeX or Microsoft Word format, it is straightforward to convert it into a Jupyter Book with TU Delft’s specialized tools. The conversion process can be done in a few clicks using these scripts.
If you have a book that is already written in LaTeX or Microsoft Word format, you can convert it into a Jupyter Book with our developed conversion scripts. The conversion process can be done in a few clicks using these scripts.
## LaTeX/Word to Jupyter Book
Currently, we are working on python scripts to convert LaTeX & Word files into Jupyter Book files. As this feature is still under development, please [contact](contact.md) us if you are interested.
<!-- ## LaTeX to Jupyter Book
A python script has been developed to convert your LaTeX file to JB. It can be accessed [here](https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion).
## LaTeX to Jupyter Book
A python script has been developed to convert your LaTeX files to MarkDown files for a Jupyter Book. It can be accessed [here](https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion).
### Steps to use the script
Before converting your LaTeX files, it must be ensured that all chapters are in separate folders. Each chapter folder must contain a .tex file, which consists of the contents of the chapter. The folder can contain sub-folders to indicate sub-chapters which must follow a similar structure.
:::{admonition} LaTeX template
:class: warning, dropdown
For optimal conversion performance, your LaTeX content should be written following the [template LaTeX document](https://gitlab.tudelft.nl/opentextbooks/latex-template). The script should be able to convert all LaTeX files in this template (except the `main` file) to MarkDown. The template shows how to include image source files, problem source files and other commonly used features. Please note that the `main` file of the LaTeX template only includes other files and LaTeX settings; this file cannot (and need not) be converted to MarkDown (and will throw an error if you try).
:::
Once the repository has been cloned onto your local system, where your LaTeX book exists, the script can now be used for the conversion.
You can either download the `latextomarkdown.py` or clone [the repository](https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion) onto your local system, where your LaTeX book exists. Each LaTeX file (chapter) must be individually converted using the script.
Note that each chapter must be individually converted using the script.
:::{admonition} `cleanlatex.py`
:class: note
Before running the conversion script, you can clean up your LaTeX files using the `cleanlatex.py` script from [the same repository](https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion). The script does not change the output of the LaTeX, but it removes comments and superfluous whitespace and changes the syntax of linebreaks for smoother conversion.
:::
In `latextomarkdown.py`, edit the basepath in the main function to point to the folder of the chapter to be converted.
......@@ -24,7 +26,7 @@ Then, run the script in the command line and provide the .tex filename as the ar
Note that you only need to provide the file name without the .tex extension as shown above.
The markdown file (.md) will be generated and stored in the same folder alongside the .tex file. -->
The markdown file (.md) will be generated and stored in the same folder alongside the .tex file.
```{admonition} PDF generation
......@@ -32,8 +34,8 @@ The markdown file (.md) will be generated and stored in the same folder alongsid
Jupyter Book is able to generate a PDF. However, if you have a LaTeX file it is beter to construct your PDF from there.
```
<!-- ## Word to Jupyter Book
## Word to Jupyter Book
For the conversion of Microsoft Word files to Jupyter Book, please [contact](contact.md) us.
For the conversion of Microsoft Word files to Jupyter Book, please [contact](contact.md) us. -->
<!-- #endregion -->
content/additional/fig_animation.md deleted 100644 → 0
+ 0
− 101
View file @ daef4aba
# Creating Animated Figures with Matplotlib
In this chapter, we will explore creating animated figures using Matplotlib animations.
## Requirements
Before getting started with creating animated figures using Matplotlib, make sure you have the following requirements in place:
- Python installed on your system
- Matplotlib library installed
- IPython library installed
## Sources
To learn more about creating animated figures using Matplotlib, you can refer to the following resources:
- [Matplotlib Animation API](https://matplotlib.org/stable/api/animation_api.html): This documentation provides insights into how the animation method works internally and offers multiple coding examples.
- [Matplotlib FuncAnimation](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.FuncAnimation.html): Here, you can find detailed information about the parameters of the FuncAnimation function and the methods it provides.
In the next sections, we will guide you through the main steps, provide a brief explanation, and present a code example.
## The method
The `FuncAnimation` module creates an animation by repeatedly calling a function (`func` argument). Each call generates one frame of the animation. The `frames` argument specifies the source of data to pass to the `func` for each frame.
The main arguments needed for the animation are as follows:
- `fig`: A figure object that serves as the canvas for the animation.
- `func`: The function to call at each frame. This function should update the information of the figure object to capture the frame in the animation.
- `frames=None`: The domain of values for which a frame will be created. The `func` function is called with each value from the `frames` argument.
It's important to note that the `funcAnimation` first calls the `func` function and then draws the content of the `fig` object at each frame. Therefore, the `func` function should update the figure object to reflect the desired changes for each frame.
> **Note:** For more information and examples, refer to the [Matplotlib Animation API documentation](https://matplotlib.org/stable/api/animation_api.html).
## Coding example
The following code example demonstrates how to create an animated figure using Matplotlib:
```python
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.animation as animation
from IPython.display import HTML
plt.rcParams["animation.html"] = "jshtml" # Set the animation format to "jshtml"
x = np.linspace(0, 2 * np.pi, 100)
fig, ax = plt.subplots() # Create a figure and axes object
line, = ax.plot(x, np.sin(x))
def update(frame):
line.set_ydata(np.sin(x + frame)) # Update the y-data of the line with the new frame value
ani = animation.FuncAnimation(fig, update, frames=x) # Create the animation object
plt.close(fig) # Prevent the initial figure from being displayed inline
HTML(ani.to_jshtml()) # Display the animation as HTML
```
Or another example, which can be found in the [Open Quantum Sensing and Measurement Notes](https://interactivetextbooks.tudelft.nl/qsm/src/5_wigner_2.html#change-phase-of-alpha) is:
```python
from qutip import *
N = 30
fig, ax = plt.subplots(1, 1, figsize=(4, 4))
def update(phi):
ax.cla()
psi = coherent(N,3*np.exp(1j*phi)) + coherent(N,-3*np.exp(1j*phi))
plot_wigner(psi,fig=fig,ax=ax)
phi_values = np.linspace(0, 2*np.pi, 100)
anim = animation.FuncAnimation(fig, update, frames=phi_values)
plt.close(fig) # Close the figure to prevent it from displaying inline
HTML(anim.to_jshtml())
```
## General process
The general process to create an animated figure using Matplotlib is as follows:
1. Ensure that the necessary packages are installed.
2. Define the figure object, e.g. using `plt.subplots()`.
3. Specify the frames argument, which determines the domain of values for creating each frame.
4. Define the func function that will be called for each frame. This function should update the figure object accordingly. The first argument will be the frame value and [additional arguments](https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.FuncAnimation.html#:~:text=The%20function%20to%20call%20at%20each%20frame.%20The%20first%20argument%20will%20be%20the%20next%20value%20in%20frames.%20Any%20additional%20positional%20arguments%20can%20be%20supplied%20using%20functools.partial%20or%20via%20the%20fargs%20parameter.) can be added if needed.
5. Create the `FuncAnimation` object by providing the above-mentioned arguments and any other relevant arguments.
6. Set the `animation.html` ([link](https://matplotlib.org/stable/users/explain/customizing.html#:~:text=%2D%20%27jshtml%27%20creates%20a%20JavaScript%20animation)) parameter to "jshtml" to plot the animation as HTML.
7. Generate the HTML representation of the animation using the `.to_jshtml()` function and convert the result to HTML using the `IPython.display.HTML` method.
For more details and examples, refer to the [Matplotlib Animation API documentation](https://matplotlib.org/stable/api/animation_api.html).
### Remark
When compiling your book locally, the default cell execution time-out is set to 30 seconds. However, given that certain animations may require additional processing time, it is recommended to extend the execution time, such as to 300 milliseconds. This adjustment can be made by configuring the timeout for all notebook executions in your `_config.yml` file (see [here](https://jupyterbook.org/en/stable/content/execute.html#setting-execution-timeout)) using the following approach:
```
execute:
timeout: 300
```
\ No newline at end of file
content/additional/links.md
+ 8
− 2
View file @ 5d84a4c7
......@@ -2,12 +2,16 @@
This page includes useful links to the most important features that this implementation of Jupyter Books can showcase through its various plugins. However, it's recommended to also read the complete official documentation in order to gain a comprehensive understanding of the capabilities at your disposal.
For information on the configuration file settings used in the template, see [template configuration](config.md).
For information on the configuration file settings used in the template, see [template configuration](template.md).
## Official documentation
- [Official Documentation](https://jupyterbook.org/)
- [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) - **Refer to this for quick reference**
## Installations
- [VSCode](https://code.visualstudio.com)
- [Anaconda](https://www.anaconda.com/download)
- [Git](https://git-scm.com/downloads)
## General structure
- [How headers and sections map onto to book structure](https://jupyterbook.org/en/stable/structure/sections-headers.html)
......@@ -15,7 +19,8 @@ For information on the configuration file settings used in the template, see [te
- [Components and UI elements](https://jupyterbook.org/en/stable/content/components.html)
- [Hide or remove content](https://jupyterbook.org/en/stable/interactive/hiding.html)
- [Control the page layout](https://jupyterbook.org/en/stable/content/layout.html)
- [Syntax Extensions](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html)
- [Execute and cache your pages](https://jupyterbook.org/content/execute.html)
## References / Citations
- [Get started with references](https://jupyterbook.org/en/stable/tutorials/references.html)
......@@ -25,6 +30,7 @@ For information on the configuration file settings used in the template, see [te
## Math
- [Math and equations](https://jupyterbook.org/en/stable/content/math.html)
- [Math and equations/Latex-style math](https://jupyterbook.org/en/stable/content/math.html#latex-style-math)
- [Proofs, Theorems, and Algorithms](https://jupyterbook.org/en/stable/content/proof.html)
- [Sphinx-proof Documentation](https://sphinx-proof.readthedocs.io/en/latest/)
- [SciPy documentation](https://docs.scipy.org/doc/scipy/)
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment