manual_teachbooks/book/intro.md

file_format	kernelspec
mystnb	name python3

TeachBooks Manual

Nesting inside of a start-directive

Different directives

::::{prf:theorem-start} The parent theorem 🏷️ parent-theorem-label

This is a parent theorem. This text is inside the parent theorem.

:::{prf:axiom-start} A child theorem 🏷️ child-axiom-label

This is a child axiom. This text is inside the child directive. :::

This is text after the child-start, before the child-end, inside the parent theorem.

:::{prf:axiom-end} :::

Finally some text after the entire child, inside the theorem start.

::::

Some text after the entire parent theorem start, but before the parent theorem end.

:::{prf:theorem-end} :::

Same directives

::::{prf:theorem-start} The parent theorem 🏷️ parent-theorem-label2

This is a parent theorem. This text is inside the parent theorem.

:::{prf:theorem-start} A child theorem 🏷️ child-theorem-label

This is a child theorem. This text is inside the child directive. :::

This is text after the child-start, before the child-end, inside the parent theorem.

:::{prf:theorem-end} :::

Finally some text after the entire child, inside the theorem start.

::::

Some text after the entire parent theorem start, but before the parent theorem end.

:::{prf:theorem-end} :::

Nesting outside of a start-directive

Different directives

Crashes still:

Same directives

Crashes still:

Examples with code

Block directive with also a figure

:::{prf:theorem-start} A title 🏷️ theorem-label

This is a theorem. This text is inside the directive. :::

Now some extra text that should come inside the theorem.

:::{figure} images/sphinx-logo.svg :alt: Sphinx logo :width: 200px :align: center

Sphinx is a great tool for documentation! This figure should be inside the theorem. :::

a = "This is some"
b = "Python code"
c = "that should be inside the theorem."
print(f"{a} {b} {c}")

:::{prf:theorem-end} :::

Figure directive with nothing with also another figure

:::{figure-start} images/nothing.svg :name: figure-label :alt: Nothing :align: center

This is a figure. This text is inside the caption. :::

a = "This is some"
b = "Python code"
c = "that should be inside the figure,"
d = "above the caption."
print(f"{a} {b} {c} {d}")

Now some extra text that should come inside the figure, above the caption.

:::{figure} images/sphinx-logo.svg :alt: Sphinx logo :width: 200px :align: center

Sphinx is a great tool for documentation! This figure should be inside the parent figure, above the parent caption. :::

:::{figure-end} :::

This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on a TeachBook: a v1 using the Sphinx backend with additional editing tools and book features. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!), ease the editing process for anyone, and provide additional features developed for education-purposes. We hope you find this resource useful and refer back to it often.

TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our open source community beyond Delft and welcome contributions from all users.

For more information about TeachBooks, visit https://teachbooks.io/. Do not hesitate to reach out via email at info@teachbooks.io or contribute on GitHub via discussions, issues or pull requests.

Happy book building!

How to Use this Manual

There are several "parts" to the manual:

• Your First TeachBook! introduces the essential platforms and workflows, and contains a workshop that can be completed independently or as part of a TeachBooks training. We recommend even experienced Jupyter Book v1 users go through this material to better understand the TeachBooks vision on how to make books collaboratively, as this drives much of our tool development. The workshop is designed to be completed in 1-2 hours and does not require any prior knowledge or installation (just a GitHub account).
• Getting Going! begins with an overview of User Types, which are used to help understand which parts of the Manual are most relevant to you. Detailed software installation instructions, book and team setup and workflows are also provided in this part.
• The Features part describes a suite of tools that are useful for teachers, many of which are developed by TeachBooks contributors specifically for use in education. Many of these tools are illustrated in the Examples.
• A few special tools are included in the Editing Tools that are useful when writing content.

See the final chapters of this book (under Miscellaneous) for additional information about References, Credits, etc.