Skip to content
Snippets Groups Projects
Commit 40461780 authored by huibbaetsen's avatar huibbaetsen
Browse files

Remove build files

parent 7ea33b6e
No related branches found
No related tags found
1 merge request!3Manali updates
Showing
with 0 additions and 778 deletions
File deleted
File deleted
File deleted
File deleted
File deleted
File deleted
File deleted
File deleted
File deleted
File deleted
File deleted
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 76c9346d7beb9558d7335602d50ca6ed
tags: 645f666f9bcd5a90fca523b33c5a78b7
# Template configuration File
You can configure your 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 has 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 quotation marks 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 these if absolutely necessary. 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. This will be placed in the left navigation bar.
`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`
: This indicates whether to execute notebooks at build time. This must be one of "auto", "force", "cache" or "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) that 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`
: This must be one of 'show', 'remove', 'remove-warn', 'warn', 'error' or '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`
: This indicates whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in.
`use_repository_button`
: This indicates whether to add a link to your repository button.
`use_issues_button`
: This indicates whether to add an "open an issue" button.
`use_multitoc_numbering`
: This ensures continuous numbering across parts/chapters.
`extra_navbar*`
: An extra navigation bar will be displayed underneath the left navigation bar (**optional**).
`extra_footer*`
: An extra footer 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`
: This indicates whether to include your home page in the left navigation bar.
`baseurl`
: The base URL where your book will be hosted. This is used for creating image previews and social media.
`hypothesis`
: Hypothesis for comments.
`utterances`
: Utterances for comments.
`announcement*`
: This creates 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`
: Must be one of 'pdflatex' or '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*`
: This indicates 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 Jupyter Books).
`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 out 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)
# Contact
For any questions or feedback regarding the manual, feel free to send us an email at [interactive-textbooks@tudelft.nl](mailto:interactive-textbooks@tudelft.nl).
\ No newline at end of file
<!-- #region -->
# Conversion of existing files
If you have a book that is already written in LaTeX or Microsoft Word format, there are options available to convert these to markdown.
## 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).
### 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.
Once the repository has been cloned onto your local system, where your LaTeX book exists, the script can now be used for the conversion.
Note that each chapter must be individually converted using the script.
In 'latextomarkdown.py', edit the basepath in the main function to point to the folder of the chapter to be converted.
Then, run the script in the command line and provide the .tex filename as the argument.
python3 latextomarkdown.py myfirstchapter
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.
```{admonition} PDF generation
:class: warning
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
For the conversion of Microsoft Word files to Jupyter Book, please [contact](contact.md) us.
<!-- #endregion -->
# Credits
This manual is constructed by the Online Interative Textbooks team of the faculty of Applied Sciences at Delft University of Technology.
\ No newline at end of file
# Useful references
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).
## 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)
# 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 that are used while developing a particular project.
At this time, the `requirements.txt` consists of the following packages:
```text
numpy
scipy
matplotlib
plotly
myst_nb
jupyterquiz
sphinx-exercise
sphinx-proof
sphinx-inline-tabs
jupyter-book
```
To install the required packages for your book, you can simply run:
```bash
pip install -r requirements.txt
```
## More information
Find out more on how to set up your working environment:
- [](build:create-env)
# 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}
```
# 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 has 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)
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment