feat: initial commit for 100.dathere.com and first exercise

.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: deploy-book
+
+# Run this when the master or main branch changes
+on:
+  push:
+    branches:
+    - main
+    # If your git repository has the Jupyter Book within some-subfolder next to
+    # unrelated files, you can make this run only if a file within that specific
+    # folder has been modified.
+    #
+    # paths:
+    # - some-subfolder/**
+
+# This job installs dependencies, builds the book, and pushes it to `gh-pages`
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+    - uses: actions/checkout@v3
+
+    # Install dependencies
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.11
+
+    - name: Install dependencies
+      run: |
+        python -m bash_kernel.install
+
+    # (optional) Cache your executed notebooks between runs
+    # if you have config:
+    # execute:
+    #   execute_notebooks: cache
+    # - name: cache executed notebooks
+    #   uses: actions/cache@v3
+    #   with:
+    #     path: _build/.jupyter_cache
+    #     key: jupyter-book-cache-${{ hashFiles('requirements.txt') }}
+
+    # Build the book
+    - name: Build the book
+      run: |
+        jupyter-book build .
+
+    # Upload the book's HTML as an artifact
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v2
+      with:
+        path: "_build/html"
+
+    # Deploy the book's HTML to GitHub Pages
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v2

.gitignore

@@ -0,0 +1,3 @@
+.venv
+_build
+.ipynb_checkpoints

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+    "recommendations": ["emeraldwalk.runonsave", "ritwickdey.liveserver", "ms-toolsai.jupyter", "ms-toolsai.vscode-jupyter-cell-tags"]
+}

.vscode/settings.json

@@ -0,0 +1,19 @@
+{
+    "emeraldwalk.runonsave": {
+        "shell": "/bin/bash",
+        "commands": [
+            {
+                "match": ".md$",
+                "cmd": "source .venv/bin/activate && jb clean . && jb build ."
+            },
+            {
+                "match": ".yml$",
+                "cmd": "source .venv/bin/activate && jb clean . && jb build ."
+            },
+            {
+                "match": ".ipynb$",
+                "cmd": "source .venv/bin/activate && jb clean . && jb build ."
+            }
+        ]
+    }
+}

README.md

@@ -0,0 +1,53 @@
+# 100.dathere.com
+
+**Try out available exercises:** [100.dathere.com](https://100.dathere.com)
+
+This codebase includes source code for "100 exercises with qsv" found at [100.dathere.com](https://100.dathere.com).
+
+![100.dathere.com preview](media/100.dathere.com-preview.png)
+
+## How to run the Jupyter Book locally
+
+Ensure you are using one of the following OS/software:
+
+- Windows Subsystem for Linux 2 (not Windows) running Ubuntu
+- macOS
+- Linux
+
+0. Install the prerequisites:
+
+-   [Git](https://git-scm.com/)
+-   [Visual Studio Code](https://code.visualstudio.com/) - Code editor
+    -   [Live Server extension](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) - Local server extension (to view Jupyter Book locally and hot reload)
+    -   [Run on Save extension](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave) - Allows for auto-build on save for the file types specified in [../.vscode/settings.json](../.vscode/settings.json)
+-   [Python](https://python.org/)
+-   [uv](https://github.com/astral-sh/uv) - Python package manager
+
+1. Clone the repository to your local device using [Git](https://git-scm.com/):
+
+```bash
+git clone https://github.com/dathere/100.dathere.com.git
+```
+
+3. Change your directory into this folder `book`.
+4. Run `uv venv`, this should generate a `.venv` folder.
+5.
+
+-   On macOS and Linux
+    -   Run `source .venv/bin/activate`
+-   On Windows
+    -   Run `.venv\Scripts\activate`
+
+6. Run `uv pip install -r requirements-local.txt`.
+7. Run `uv pip install -e ./bash_kernel` and then `python -m bash_kernel.install` to install the Bash kernel.
+8. Run `jb build .` to build the book or save a `.md`, `.ipynb`, or `.yml` file in VS Code for the Run on Save extension to run relevant commands.
+9. Right click on `_build/html/index.html` and click Open with Live Server which should launch a local build of the website and should reload within a few seconds each time you save a `.md` or `.yml` file in VS Code (you may need to refresh the page once Run on Save is done each time).
+
+![Live Server example](media/live-server-example.png)
+
+---
+
+© Copyright [datHere](https://dathere.com)
+
+![datHere logo dark](media/datHere-logo.png#gh-dark-mode-only)
+![datHere logo light](media/datHere-logo.png#gh-light-mode-only)

_config.yml

@@ -0,0 +1,47 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: 100 exercises with qsv
+author: "<a href='https://dathere.com'>datHere</a> and <a href='https://github.com/dathere/100.dathere.com/graphs/contributors'>contributors</a>."
+logo: media/qsv-logo.png
+exclude_patterns:
+    [
+        "README.md",
+        ".venv",
+        ".vscode",
+        ".gitignore",
+        "postBuild",
+        "requirements*.txt",
+        "bash_kernel"
+    ]
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+    execute_notebooks: force
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+    use_repository_button: true
+    favicon: media/qsv-logo-dark-icon.png
+    extra_footer: |
+        <p>
+        © Copyright datHere
+        </p>
+
+# Information about where the book exists on the web
+repository:
+    url: https://github.com/dathere/100.dathere.com # Online location of your book
+    branch: main # Which branch of the repository should be used when creating links (optional)
+launch_buttons:
+    notebook_interface: jupyterlab
+    binderhub_url: https://mybinder.org
+sphinx:
+    config:
+        html_show_copyright: false
+        html_theme_options:
+          logo:
+              image_light: media/qsv-logo.png
+              image_dark: media/qsv-logo-dark.png
+    language: en

_toc.yml

@@ -0,0 +1,14 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+title: Introduction
+chapters:
+    - file: exercises-setup
+    - file: notes
+      title: Getting started
+      sections:
+          - file: lessons/0/notes
+            title: Exploring qsv help messages and syntax
+    - file: appendix

appendix.md

@@ -0,0 +1,55 @@
+---
+jupytext:
+    text_representation:
+        extension: .md
+        format_name: myst
+kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+---
+
+# Appendix
+
+Here you may find conceptual content related to the exercises in the book.
+
+## qsv version
+
+qsv has multiple versions and may differ for each system. Here we run [a command](https://github.com/jqnatividad/qsv/blob/master/docs/PERFORMANCE.md#version-details) to show what version of qsv this book is using along with other information:
+
+```bash
+qsv --version
+```
+
+```{code-cell} python3
+:tags: [remove-input, scroll-output]
+
+result = !qsv --version
+print(result.n)
+
+```
+
+## qsv release assets
+
+A mapping of qsv release files for an arbitrary version X.Y.Z and platforms they may run on are shown in the table below.
+
+```{table} qsv release assets (vX.Y.Z)
+:name: qsv-release-assets
+
+| File                                      | Platform |
+| ----------------------------------------- | ------------------------- |
+| `qsv-X.Y.Z-x86_64-pc-windows-msvc.zip`    | 64-bit MSVC (Windows 10+)            |
+| `qsv-X.Y.Z.msi`                           | Windows                   |
+| `qsv-X.Y.Z-x86_64-pc-windows-gnu.zip`     | 64-bit MinGW (Windows 10+)            |
+| `qsv-X.Y.Z-i686-pc-windows-msvc.zip`      | 32-bit MSVC (Windows 10+)               |
+| `qsv-X.Y.Z-aarch64-apple-darwin.zip`      | ARM64 macOS (11.0+, Big Sur+)       |
+| `qsv-X.Y.Z-x86_64-apple-darwin.zip`       | 64-bit macOS (10.12+, Sierra+)      |
+| `qsv-X.Y.Z-aarch64-unknown-linux-gnu.zip` | ARM64 Linux (kernel 4.1, glibc 2.17+)                 |
+| `qsv-X.Y.Z-x86_64-unknown-linux-gnu.zip`  | 64-bit Linux (kernel 3.2+, glibc 2.17+)              |
+| `qsv-X.Y.Z-x86_64-unknown-linux-musl.zip` | 64-bit Linux with musl 1.2.3              |
+| `qsv-X.Y.Z-i686-unknown-linux-gnu.zip`    | 32-bit Linux (kernel 3.2+, glibc 2.17+)                 |
+```
+
+:::{note}
+The listed OS/architecture are primarily based on [information from "The rustc book"](https://doc.rust-lang.org/nightly/rustc/platform-support.html).
+:::

bash_kernel/.gitignore

@@ -0,0 +1,5 @@
+__pycache__
+*.pyc
+build/
+dist/
+MANIFEST

bash_kernel/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2015, Thomas Kluyver and contributors 
+All rights reserved.
+
+BSD 3-clause license:
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

bash_kernel/README.rst

@@ -0,0 +1,22 @@
+A simple IPython kernel for bash
+
+This requires IPython 3.
+
+To install::
+
+    pip install bash_kernel
+    python -m bash_kernel.install
+
+To use it, run one of:
+
+.. code:: shell
+
+    ipython notebook
+    # In the notebook interface, select Bash from the 'New' menu
+    ipython qtconsole --kernel bash
+    ipython console --kernel bash
+
+For details of how this works, see the Jupyter docs on `wrapper kernels
+<http://jupyter-client.readthedocs.org/en/latest/wrapperkernels.html>`_, and
+Pexpect's docs on the `replwrap module
+<http://pexpect.readthedocs.org/en/latest/api/replwrap.html>`_

bash_kernel/bash_kernel/__init__.py

@@ -0,0 +1,3 @@
+"""A bash kernel for Jupyter"""
+
+__version__ = '0.4.1'

bash_kernel/bash_kernel/__main__.py

@@ -0,0 +1,3 @@
+from ipykernel.kernelapp import IPKernelApp
+from .kernel import BashKernel
+IPKernelApp.launch_instance(kernel_class=BashKernel)

bash_kernel/bash_kernel/images.py

@@ -0,0 +1,48 @@
+import base64
+import imghdr
+import os
+
+#from IPython.
+
+_TEXT_SAVED_IMAGE = "bash_kernel: saved image data to:"
+
+image_setup_cmd = """
+display () {
+    TMPFILE=$(mktemp ${TMPDIR-/tmp}/bash_kernel.XXXXXXXXXX)
+    cat > $TMPFILE
+    echo "%s $TMPFILE" >&2
+}
+""" % _TEXT_SAVED_IMAGE
+
+def display_data_for_image(filename):
+    with open(filename, 'rb') as f:
+        image = f.read()
+    os.unlink(filename)
+
+    image_type = imghdr.what(None, image)
+    if image_type is None:
+        raise ValueError("Not a valid image: %s" % image)
+
+    image_data = base64.b64encode(image).decode('ascii')
+    content = {
+        'data': {
+            'image/' + image_type: image_data
+        },
+        'metadata': {}
+    }
+    return content
+
+
+def extract_image_filenames(output):
+    output_lines = []
+    image_filenames = []
+
+    for line in output.split("\n"):
+        if line.startswith(_TEXT_SAVED_IMAGE):
+            filename = line.rstrip().split(": ")[-1]
+            image_filenames.append(filename)
+        else:
+            output_lines.append(line)
+
+    output = "\n".join(output_lines)
+    return image_filenames, output