admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

first part: update pages

Browse source
This commit is contained in:
Robert Lanzafame 2024-12-12 05:45:55 +01:00
parent dcbe6bd1ce
commit 7d776da225
5 changed files with 43 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

2
book/installation-and-setup/tools.md
View file

@ -58,7 +58,7 @@ On GitLab a webserver is required to process book-changes online. Both we and ot
### Setting up book repository and website
On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md).
On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:teachbooks@tudelft.nl) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online.
On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:info@teachbooks.io) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online.
### Book access with SSO
When you’re releasing your book on a server on which you're in control (connected to GitLab or GitHub), you can set up SSO login for visitors of the website. This can be arranged for on the TeachBooks server.

2
book/intro/book.md
View file

@ -10,7 +10,7 @@ Three parts to a book:
3. Content for your book! Text-based files.
```{admonition} Text-based files? yml? What is that?!
:class: tip
:class: tip, dropdown
Text-based files are digital files on your computer that you can open in a text editor and read directly. There are many file extensions used for text-based files, a few common ones related to Jupyter Book are: Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), and YAML (`*.yml`).

4
book/intro/next.md
View file

@ -1,4 +1,4 @@
# What's next?
# You Know the Basics: What Next?
You've seen what a JupyterBook is, how TeachBooks tries to help you with making those, and what the potential is in teaching. So what's next?
@ -17,4 +17,4 @@ In the next part of this manual 'Getting going!', we'll explain which options yo
Furthermore, in the 'Features' part we'll collect a suite of existing open-source software to ease the editing process, add functionalities, improve styling and improve the student-experience. Finally, the 'Examples' page contain some example pages of some book.
We hope you enjoin making books with TeachBooks. If you encouter any problem, please reach out to us on [email](mailto:info@teachbooks.io) or our [GitHub Discussions](https://github.com/orgs/TeachBooks/discussions). We'd be happy to collaborate with you or simple receive some feedback, examples, cool ideas. Happy book building!
We hope you enjoin making books with TeachBooks. If you encounter any problem, please reach out to us on [email](mailto:info@teachbooks.io) or our [GitHub Discussions](https://github.com/orgs/TeachBooks/discussions). We'd be happy to collaborate with you or simple receive some feedback, examples, cool ideas. Happy book building!

47
book/intro/template.md
View file

@ -1,4 +1,4 @@
# Make a book with 10 clicks!
# It only takes 10 clicks!
```{figure} figures/template.jpg
---
@ -7,16 +7,45 @@ width: 150px
align: right
```
Now that you've been introduced to the basics of a Jupyter Book, let's start making one! To make it very ease, we make use of GitHub to store your files online and host your website.
Now that you've been introduced to the basics of a Jupyter Book, let's make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a Jupyter Book, as well as the tools and essential workflows associated with the editing, checking and review processes.
## 1. Create a GitHub account
To get started, you need a GitHub account (not counted within the 10 clicks 🤭): https://github.com/signup
TeachBooks relies of freely available services from GitHub to store files online, carry out the book-building process and host your book as a website. All you need to get started is a GitHub account (not counted in the 10 clicks 🤭).
## 2. Use the template
Now, let's start making a book. Therefore, we've made a template on GitHub which covers most of the technical steps required to have your book online. How to start using the template is explained in the `README` of the template, which is shown on the homepage of the template: https://github.com/TeachBooks/template. Please follow the steps provided there. When you're done, come back here!
```{admonition} Task 1
:class: tip
## 3. Let's practice!
You should have your book now online on something like `<your_username>.github.io/<book>`.
If you don't already have one, create a GitHub account here by visiting [github.com/signup](https://github.com/signup).
```
Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start. Therefore, exercises are included in the template you used took! You can go over them and look at the results online.
## 2. Use the template---it's really just 10 clicks!
Now, let's make a book: we've made a template on GitHub which carries out _most_ of the technical steps required to create a book and put it online. Instructions for using the template are in the `README` of the TeachBooks Template repository on GitHub, which is by default visible on the repository homepage: [github.com/TeachBooks/template](https://github.com/TeachBooks/template).
```{admonition} Task 2
:class: tip
Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBooks/template) and follow the instructions to create your book. When finished, come back to this page.
```
## 3. Check out your book!
Shortly after you create a book it will be available online at `<your_username>.github.io/<book>`.
```{admonition} Task 3
:class: tip
Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBooks/template) and follow the instructions to create your book. When finished, come back to this page.
```
## 4. Let's practice!
Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you as part of an introductory **workshop**. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages.
```{admonition} Task 4
:class: tip
Work through the sections attached to this page (you can find them in the left sidebar).
```
```{tip}
If you find that the exercises are too easy for you, jump to the last page in this section, which summarizes all tasks and exercises that should be completed to fully understand how to create collaborate with TeachBooks.
```

2
book/intro/workflow.md
View file

@ -1 +1 @@
# Process
# How can you do it?