From 70f4632ee1c4f1e7ec3eb6a036caa9faa48ffea2 Mon Sep 17 00:00:00 2001
From: Theodosis <t.athanasakis@student.tudelft.nl>
Date: Sat, 18 Mar 2023 21:36:12 +0100
Subject: [PATCH] Enhanced process
---
content/basics/conversion.md | 2 +-
content/basics/process/build.md | 6 +++---
content/basics/process/create.md | 2 +-
content/basics/process/install.md | 36 ++++++++++++++++++++++++++-----
content/basics/process/publish.md | 2 +-
5 files changed, 37 insertions(+), 11 deletions(-)
diff --git a/content/basics/conversion.md b/content/basics/conversion.md
index 8116283..ed9669c 100644
--- a/content/basics/conversion.md
+++ b/content/basics/conversion.md
@@ -1,6 +1,6 @@
# Conversion of existing files
-In case you have already a book written in LaTex or Microsoft Word format, it is ver easy to convert it into a Jupyter Book. [Timon Idema]() and ... have developed tools to make this process easier and wit e click of a button.
+In case you have already a book written in LaTex or Microsoft Word format, it is ver easy to convert it into a Jupyter Book. Timon Idema and ... have developed tools to make this process easier and wit e click of a button.
## LaTeX to Jupyter Book
diff --git a/content/basics/process/build.md b/content/basics/process/build.md
index ab8c333..3f642ba 100644
--- a/content/basics/process/build.md
+++ b/content/basics/process/build.md
@@ -13,7 +13,7 @@ In order to build the HTML for each page, you should have followed the steps in
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.
@@ -34,7 +34,7 @@ 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 of TU Delft.
:::{admonition} Delete environment
-:class: tip, dropdown
+:class: seealso, dropdown
If you want to remove an environment, run the following command:
@@ -52,7 +52,7 @@ conda activate env-name
```
:::{admonition} Deactivate environment
-:class: tip, dropdown
+:class: seealso, dropdown
If you want to deactivate an environment, run the following command:
diff --git a/content/basics/process/create.md b/content/basics/process/create.md
index f9c60fc..d2910a7 100644
--- a/content/basics/process/create.md
+++ b/content/basics/process/create.md
@@ -22,7 +22,7 @@ For example, take a look at the template book that you just downloaded:
```console
$ tree template-book
template-book/
-├── images
+├── content
├── _config.yml
├── _toc.yml
├── intro.md
diff --git a/content/basics/process/install.md b/content/basics/process/install.md
index 178fda5..6e0d18a 100644
--- a/content/basics/process/install.md
+++ b/content/basics/process/install.md
@@ -3,30 +3,54 @@
In order to create and work on your Jupyter Book, you need to download some programs. Please, find below all the required programs
-## Conda & Anaconda
+## 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.
-```{warning} A note for Windows users
+```{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.
```
-```{note}
+```{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` or `Aanaconda Prompt`.
+
+Find more at: [Terminal emulator](https://www.jetbrains.com/help/dataspell/terminal-emulator.html)
+```
+
+
## Install Jupyter Book
-You can install Jupyter Book via the command line (having downloaded [`conda-forge`](https://conda-forge.org/)):
+You can install Jupyter Book via [`pip`](https://pip.pypa.io/en/stable/):
```bash
-conda install -c conda-forge jupyter-book
+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)
@@ -44,3 +68,5 @@ Find more information about creating your book:
- [Miniconda](https://docs.conda.io/en/latest/miniconda.html)
- [DataSpell](https://www.jetbrains.com/dataspell/)
- [VSCode](https://code.visualstudio.com/)
+- ['Conda' is not recognized as internal or external command](https://stackoverflow.com/questions/44515769/conda-is-not-recognized-as-internal-or-external-command)
+- [Terminal emulator](https://www.jetbrains.com/help/dataspell/terminal-emulator.html)
diff --git a/content/basics/process/publish.md b/content/basics/process/publish.md
index abd9850..e69eeae 100644
--- a/content/basics/process/publish.md
+++ b/content/basics/process/publish.md
@@ -68,7 +68,7 @@ NB: This is a hands-on instruction for use on a terminal. No need to do any of t
########################################################
## Publish your book online with GitLab Pages
-We have just pushed the *source files* for our book into our GitHub repository. This makes it publicly accessible for you or others to see.
+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.
Next, we'll publish the *build artifact* of our book online, so that it is rendered as a website.
--
GitLab