From 56b044ddd2285a214be7f326f63f2f2c189f0a86 Mon Sep 17 00:00:00 2001 From: Isabel Slingerland Date: Sun, 3 Mar 2024 17:53:23 +0100 Subject: [PATCH 1/4] edited_basic_feature_overview --- book/basic-features/overview.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index 1dd46cd..e75ad2b 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -1,11 +1,16 @@ # Basic Features -```{warning} Under Construction! +A short description on basic features is given here. An overview of the basic features is given here: +- Figures +- Videos +- Equations +- Code blocks to produce figures +- References +- Code +- Notebooks -This page will provide a list of some commonly used book features which are all available in the original jupyter book package. However, this page includes best-practises on how to use them. -``` -Things to include somewhere: +Things to be aware of: - use the right HTML tags for images (described {ref}`here `) - watch out for `png` versus `PNG` - 2 interesting comments from Quinten about MyST extensions in [this GL Issue](https://gitlab.tudelft.nl/mude/archive-2022/-/issues/25#note_163123) From 4da8e3a47881b66291aca279582bad8b19802bc9 Mon Sep 17 00:00:00 2001 From: Isabel Slingerland Date: Sun, 3 Mar 2024 17:54:25 +0100 Subject: [PATCH 2/4] removed_double_text --- book/basic-features/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index e75ad2b..14c87e7 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -1,6 +1,6 @@ # Basic Features -A short description on basic features is given here. An overview of the basic features is given here: +A short description on basic features is given here: - Figures - Videos - Equations From 040d08b7b31d138f12b8ddb39fa8372b77b2a78f Mon Sep 17 00:00:00 2001 From: Caspar Jungbacker <74240267+CasparJungbacker@users.noreply.github.com> Date: Fri, 11 Aug 2023 17:56:52 +0200 Subject: [PATCH 3/4] Relocate --- book/jupyter-book-basics/jupyterbook.md | 77 +++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 book/jupyter-book-basics/jupyterbook.md diff --git a/book/jupyter-book-basics/jupyterbook.md b/book/jupyter-book-basics/jupyterbook.md new file mode 100644 index 0000000..427f819 --- /dev/null +++ b/book/jupyter-book-basics/jupyterbook.md @@ -0,0 +1,77 @@ +# Anatomy of a Jupyter Book + +To build a Jupyter Book, you need three things: + +1. A configuration file +2. A table of contents +3. Content + +## The configuration file +The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book: + +```yml +title: Jupyter Book Manual +author: Interactive Textbooks CiTG +logo: images/TUDelft_logo_rgb.png + +execute: + execute_notebooks: auto + +sphinx: + extra_extensions: + - sphinx_inline_tabs +``` + +Technically speaking, a `_config.yml` file is not required to build a Jupyter Book. If you don't make one, `jupyter book` will just use all default values. However, you should make a configuration file with at least the following settings: + +- `title`: the title of your book, which appears on the top-left of every page, under the logo. +- `author`: authors of the book, which appears in the bottom margin of every page. +- `logo`: (relative) path to the logo of your book (optional). + +In addition, the following option can also be useful: + +- `execute_notebooks`: turn on/off the execution of Jupyter Notebooks during the build process. On by default. If you perform heavy computations in your notebook (machine learning, FEM models, et cetera), you might be better off running the notebooks on a more powerful machine as opposed to the CI/CD server. To turn it off, specify the value `'off'`. You can also exclude specific notebooks by creating exclude patterns in the filenames. For more info, see the [Jupyter Book documentation](https://jupyterbook.org/en/stable/content/execute.html#exclude-files-from-execution). + + +```{warning} +The coniguration and table of contents files are in YAML format (short for YAML Ain't Markup Language). YAML has a specific syntax, which can cause some errors if you don't adhere to it. Just like Python, indentation is very important. You can find an overview of the syntax [here](https://en.wikipedia.org/wiki/YAML#Syntax). +``` + +## The table of contents + +The table of contents (`_toc.yml`) file is where you define the structure of your book. You can organize content in *parts*, *chapters*, and *sections*. This is what a table of contents could look like: + +```yml +- format: jb-book +- root: intro + +chapters: +- file: chapter_1 + sections: + - file: subsection_1 + - file: subsection_2 +- file: chapter_2 + +et cetera... +``` + +`root` is the landing page of your book. It will be the first page that people see when they visit the book. You can include files by providing their *relative* path (so the location with respect to `_toc.yml`). These files can be a combination of Markdown, Jupyter Notebooks, and Restructured Text. The example above does not have parts, so the menu on the left will consist of just a list of the chapters. You can also group chapters in parts like this: + +```yml +- format: jb-book +- root: + +parts: +- caption: Part 1 + chapters: + - file: chapter_1 + sections: + - file: subsection_1 + - file: subsection_2 + - file: chapter_2 +- caption: Part 2 + chapters: + - file: chapter_3 + +et cetera... +``` \ No newline at end of file From f58b18afdde1a9b739cd16ba01ad1fae2e8277ef Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 29 May 2024 10:21:40 +0200 Subject: [PATCH 4/4] move file --- book/_toc.yml | 1 + book/{jupyter-book-basics => basic-features}/jupyterbook.md | 0 2 files changed, 1 insertion(+) rename book/{jupyter-book-basics => basic-features}/jupyterbook.md (100%) diff --git a/book/_toc.yml b/book/_toc.yml index 15f9117..688be97 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -26,6 +26,7 @@ parts: chapters: - file: basic-features/overview sections: + - file: basic-features/jupyterbook.md - file: basic-features/recipes.md - file: basic-features/hypothesis - file: basic-features/utterances diff --git a/book/jupyter-book-basics/jupyterbook.md b/book/basic-features/jupyterbook.md similarity index 100% rename from book/jupyter-book-basics/jupyterbook.md rename to book/basic-features/jupyterbook.md