Installation Guide

README.md

@@ -7,4 +7,4 @@
 2. write contents in a new file (e.g. `chapter1.md`). 
 3. add an entry in `_toc.yml` (e.g. `- file: markdown-notebooks`)
 4. Make a new PR to merge into the `main` branch.
-5. (for publisher/administrator) after the working branch is merged, execute `jupyter-book build .` and then `ghp-import -n -p -f _build/html`. `ghp-import` will automatically push all the changes into the `gh-pages` branch.
+5. (for publisher/administrator) after the working branch is merged, execute `jupyter-book build .` and then `ghp-import -n -p -f _build/html`. `ghp-import` will automatically push all the changes into the `gh-pages` branch. GitHub Actions will do the rest.

_build/html/README.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
 
-    <title>quisp-textbook &#8212; QuISP Textbook</title>
+    <title>QuISP Textbook &#8212; QuISP Textbook</title>
 
   <!-- Loaded before other Sphinx assets -->
   <link href="_static/styles/theme.css?digest=1999514e3f237ded88cf" rel="stylesheet">
@@ -323,7 +323,7 @@ <h1 class="site-logo" id="site-title">QuISP Textbook</h1>
         <div class="col pl-md-3 pl-lg-5 content-container">
             <!-- Table of contents that is only displayed when printing the page -->
             <div id="jb-print-docs-body" class="onlyprint">
-                <h1>quisp-textbook</h1>
+                <h1>QuISP Textbook</h1>
                 <!-- Table of contents -->
                 <div id="print-main-content">
                     <div id="jb-print-toc">
@@ -349,15 +349,16 @@ <h2> Contents </h2>
               <div>
 
   <section class="tex2jax_ignore mathjax_ignore" id="quisp-textbook">
-<h1>quisp-textbook<a class="headerlink" href="#quisp-textbook" title="Permalink to this headline">#</a></h1>
+<h1>QuISP Textbook<a class="headerlink" href="#quisp-textbook" title="Permalink to this headline">#</a></h1>
 <p><img alt="cover" src="_images/cover.jpg" /></p>
 <section id="instruction-to-edit-quisp-textbook">
 <h2>instruction to edit quisp-textbook<a class="headerlink" href="#instruction-to-edit-quisp-textbook" title="Permalink to this headline">#</a></h2>
 <ol class="simple">
-<li><p>write contents in a new file (e.g. <code class="docutils literal notranslate"><span class="pre">chapter1.md</span></code>)</p></li>
+<li><p>Create a new branch for your work, and checkout to that branch</p></li>
+<li><p>write contents in a new file (e.g. <code class="docutils literal notranslate"><span class="pre">chapter1.md</span></code>).</p></li>
 <li><p>add an entry in <code class="docutils literal notranslate"><span class="pre">_toc.yml</span></code> (e.g. <code class="docutils literal notranslate"><span class="pre">-</span> <span class="pre">file:</span> <span class="pre">markdown-notebooks</span></code>)</p></li>
-<li><p>in quisp-textbook directory, run <code class="docutils literal notranslate"><span class="pre">jupyter-book</span> <span class="pre">build</span> <span class="pre">.</span></code></p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">open</span> <span class="pre">_build/html/index.html</span></code> to check the generated textbook</p></li>
+<li><p>Make a new PR to merge into the <code class="docutils literal notranslate"><span class="pre">main</span></code> branch.</p></li>
+<li><p>(for publisher/administrator) after the working branch is merged, execute <code class="docutils literal notranslate"><span class="pre">jupyter-book</span> <span class="pre">build</span> <span class="pre">.</span></code> and then <code class="docutils literal notranslate"><span class="pre">ghp-import</span> <span class="pre">-n</span> <span class="pre">-p</span> <span class="pre">-f</span> <span class="pre">_build/html</span></code>. <code class="docutils literal notranslate"><span class="pre">ghp-import</span></code> will automatically push all the changes into the <code class="docutils literal notranslate"><span class="pre">gh-pages</span></code> branch. GitHub Actions will do the rest.</p></li>
 </ol>
 </section>
 </section>

_build/html/_sources/README.md

@@ -1,10 +1,10 @@
-# quisp-textbook
+# QuISP Textbook
 
 ![cover](cover.jpg "Cover")
 
 ## instruction to edit quisp-textbook
-
-1. write contents in a new file (e.g. `chapter1.md`)
-2. add an entry in `_toc.yml` (e.g. `- file: markdown-notebooks`)
-3. in quisp-textbook directory, run `jupyter-book build .`
-4. `open _build/html/index.html` to check the generated textbook
+1. Create a new branch for your work, and checkout to that branch
+2. write contents in a new file (e.g. `chapter1.md`). 
+3. add an entry in `_toc.yml` (e.g. `- file: markdown-notebooks`)
+4. Make a new PR to merge into the `main` branch.
+5. (for publisher/administrator) after the working branch is merged, execute `jupyter-book build .` and then `ghp-import -n -p -f _build/html`. `ghp-import` will automatically push all the changes into the `gh-pages` branch. GitHub Actions will do the rest.

_build/html/_sources/getting-started.md

@@ -1 +1,82 @@
 # Getting Started
+
+Okay, enough talks. Now let's see how quisp is working with our bare eyes. We have to build QuISP in our machine for that.
+
+> :warning: **Building the software from source** might look awkward to some developers with interpreter-based languages (such as Python, Lua, JS...). We are going to add the software build section to the textbook, explaining the architecture of GNU `make` and the concept of `makemake` we are using with OMNeT++. Don't switch the channel! For now, you can follow our manual to get the correct result.
+
+## Installation
+
+### Recommended Environment
+- Docker with at least 6GB of allocated RAM (you can change that in Docker Desktop Settings)
+...and that's it!
+
+The following procedures were confirmed working on the MacOS Catalina (10.15.3) and Mojave(10.14).
+
+### TL;DR
+- Install brew, docker, XQuartz and socat with `sh docker_tools.sh`
+- clone quisp
+- `docker pull ghcr.io/sfc-aqua/quisp`
+- Run docker with `sh docker_run.sh`
+- Run `omnetpp` command on the docker container
+
+---
+
+### Automated way
+
+1. Open your terminal and run
+
+```zsh
+$ git clone https://github.com/sfc-aqua/quisp.git
+```
+
+You can download quisp from github.
+Enter quisp with `cd quisp`
+2. Run shell script
+
+```zsh
+$ sh docker_tools.sh
+```
+
+After you have successfully installed the related tools, please reboot your laptop. (Maybe just rebooting your terminal is enough.)
+
+3. Build docker container
+
+Open terminal and run,
+
+```zsh
+$ docker pull ghcr.io/sfc-aqua/quisp
+```
+
+A docker image called quisp should have been created. You can check with the command `docker images`.
+
+4. Run docker container
+
+OK, now you can enter the container.
+
+```zsh
+$ sh docker_run.sh
+```
+
+If this error pops up,
+```zsh
+docker_run.sh: line 15: xhost: command not found
+docker_run.sh: line 15: xterm: command not found
+```
+add `/usr/X11/bin` (might vary) to your path
+
+5. Try quisp!
+
+If all of the processing completed successfully, you should see
+
+```zsh
+quisp:/root/quisp$
+```
+
+Open omnet with
+
+```zsh
+quisp:/root/quisp$ omnetpp
+```
+
+Enjoy quisp!
+

_build/html/_sources/markdown-notebooks.ipynb

@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "markdown",
-   "id": "abaca5fb",
+   "id": "ec9d0c81",
    "metadata": {},
    "source": [
     "# Notebooks with MyST Markdown\n",
@@ -19,7 +19,7 @@
   {
    "cell_type": "code",
    "execution_count": 1,
-   "id": "cc40d43e",
+   "id": "73c38ddc",
    "metadata": {},
    "outputs": [
     {
@@ -36,7 +36,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "d6433c54",
+   "id": "9b677916",
    "metadata": {},
    "source": [
     "When your book is built, the contents of any `{code-cell}` blocks will be\n",

_build/html/getting-started.html

@@ -288,12 +288,53 @@ <h1 class="site-logo" id="site-title">QuISP Textbook</h1>
     </ul>
   </div>
 </div>
+<label for="__page-toc"
+  class="headerbtn headerbtn-page-toc"
+
+>
+
+
+<span class="headerbtn__icon-container">
+  <i class="fas fa-list"></i>
+  </span>
+
+</label>
 
     </div>
 </div>
 
 <!-- Table of contents -->
 <div class="col-md-3 bd-toc show noprint">
+    <div class="tocsection onthispage pt-5 pb-3">
+        <i class="fas fa-list"></i> Contents
+    </div>
+    <nav id="bd-toc-nav" aria-label="Page">
+        <ul class="visible nav section-nav flex-column">
+ <li class="toc-h2 nav-item toc-entry">
+  <a class="reference internal nav-link" href="#installation">
+   Installation
+  </a>
+  <ul class="nav section-nav flex-column">
+   <li class="toc-h3 nav-item toc-entry">
+    <a class="reference internal nav-link" href="#recommended-environment">
+     Recommended Environment
+    </a>
+   </li>
+   <li class="toc-h3 nav-item toc-entry">
+    <a class="reference internal nav-link" href="#tl-dr">
+     TL;DR
+    </a>
+   </li>
+   <li class="toc-h3 nav-item toc-entry">
+    <a class="reference internal nav-link" href="#automated-way">
+     Automated way
+    </a>
+   </li>
+  </ul>
+ </li>
+</ul>
+
+    </nav>
 </div>
     </div>
     <div class="article row">
@@ -305,6 +346,36 @@ <h1>Getting Started</h1>
                 <div id="print-main-content">
                     <div id="jb-print-toc">
 
+                        <div>
+                            <h2> Contents </h2>
+                        </div>
+                        <nav aria-label="Page">
+                            <ul class="visible nav section-nav flex-column">
+ <li class="toc-h2 nav-item toc-entry">
+  <a class="reference internal nav-link" href="#installation">
+   Installation
+  </a>
+  <ul class="nav section-nav flex-column">
+   <li class="toc-h3 nav-item toc-entry">
+    <a class="reference internal nav-link" href="#recommended-environment">
+     Recommended Environment
+    </a>
+   </li>
+   <li class="toc-h3 nav-item toc-entry">
+    <a class="reference internal nav-link" href="#tl-dr">
+     TL;DR
+    </a>
+   </li>
+   <li class="toc-h3 nav-item toc-entry">
+    <a class="reference internal nav-link" href="#automated-way">
+     Automated way
+    </a>
+   </li>
+  </ul>
+ </li>
+</ul>
+
+                        </nav>
                     </div>
                 </div>
             </div>
@@ -314,6 +385,81 @@ <h1>Getting Started</h1>
 
   <section class="tex2jax_ignore mathjax_ignore" id="getting-started">
 <h1>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">#</a></h1>
+<p>Okay, enough talks. Now let’s see how quisp is working with our bare eyes. We have to build QuISP in our machine for that.</p>
+<blockquote>
+<div><p>:warning: <strong>Building the software from source</strong> might look awkward to some developers with interpreter-based languages (such as Python, Lua, JS…). We are going to add the software build section to the textbook, explaining the architecture of GNU <code class="docutils literal notranslate"><span class="pre">make</span></code> and the concept of <code class="docutils literal notranslate"><span class="pre">makemake</span></code> we are using with OMNeT++. Don’t switch the channel! For now, you can follow our manual to get the correct result.</p>
+</div></blockquote>
+<section id="installation">
+<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">#</a></h2>
+<section id="recommended-environment">
+<h3>Recommended Environment<a class="headerlink" href="#recommended-environment" title="Permalink to this headline">#</a></h3>
+<ul class="simple">
+<li><p>Docker with at least 6GB of allocated RAM (you can change that in Docker Desktop Settings)
+…and that’s it!</p></li>
+</ul>
+<p>The following procedures were confirmed working on the MacOS Catalina (10.15.3) and Mojave(10.14).</p>
+</section>
+<section id="tl-dr">
+<h3>TL;DR<a class="headerlink" href="#tl-dr" title="Permalink to this headline">#</a></h3>
+<ul class="simple">
+<li><p>Install brew, docker, XQuartz and socat with <code class="docutils literal notranslate"><span class="pre">sh</span> <span class="pre">docker_tools.sh</span></code></p></li>
+<li><p>clone quisp</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">pull</span> <span class="pre">ghcr.io/sfc-aqua/quisp</span></code></p></li>
+<li><p>Run docker with <code class="docutils literal notranslate"><span class="pre">sh</span> <span class="pre">docker_run.sh</span></code></p></li>
+<li><p>Run <code class="docutils literal notranslate"><span class="pre">omnetpp</span></code> command on the docker container</p></li>
+</ul>
+</section>
+<hr class="docutils" />
+<section id="automated-way">
+<h3>Automated way<a class="headerlink" href="#automated-way" title="Permalink to this headline">#</a></h3>
+<ol class="simple">
+<li><p>Open your terminal and run</p></li>
+</ol>
+<div class="highlight-zsh notranslate"><div class="highlight"><pre><span></span>$ git clone https://github.com/sfc-aqua/quisp.git
+</pre></div>
+</div>
+<p>You can download quisp from github.
+Enter quisp with <code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">quisp</span></code>
+2. Run shell script</p>
+<div class="highlight-zsh notranslate"><div class="highlight"><pre><span></span>$ sh docker_tools.sh
+</pre></div>
+</div>
+<p>After you have successfully installed the related tools, please reboot your laptop. (Maybe just rebooting your terminal is enough.)</p>
+<ol class="simple">
+<li><p>Build docker container</p></li>
+</ol>
+<p>Open terminal and run,</p>
+<div class="highlight-zsh notranslate"><div class="highlight"><pre><span></span>$ docker pull ghcr.io/sfc-aqua/quisp
+</pre></div>
+</div>
+<p>A docker image called quisp should have been created. You can check with the command <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">images</span></code>.</p>
+<ol class="simple">
+<li><p>Run docker container</p></li>
+</ol>
+<p>OK, now you can enter the container.</p>
+<div class="highlight-zsh notranslate"><div class="highlight"><pre><span></span>$ sh docker_run.sh
+</pre></div>
+</div>
+<p>If this error pops up,</p>
+<div class="highlight-zsh notranslate"><div class="highlight"><pre><span></span>docker_run.sh: line <span class="m">15</span>: xhost: <span class="nb">command</span> not found
+docker_run.sh: line <span class="m">15</span>: xterm: <span class="nb">command</span> not found
+</pre></div>
+</div>
+<p>add <code class="docutils literal notranslate"><span class="pre">/usr/X11/bin</span></code> (might vary) to your path</p>
+<ol class="simple">
+<li><p>Try quisp!</p></li>
+</ol>
+<p>If all of the processing completed successfully, you should see</p>
+<div class="highlight-zsh notranslate"><div class="highlight"><pre><span></span>quisp:/root/quisp$
+</pre></div>
+</div>
+<p>Open omnet with</p>
+<div class="highlight-zsh notranslate"><div class="highlight"><pre><span></span>quisp:/root/quisp$ omnetpp
+</pre></div>
+</div>
+<p>Enjoy quisp!</p>
+</section>
+</section>
 </section>
 
     <script type="text/x-thebe-config">