Merge pull request #20 from danielballan/first-recipes

Add 'Hello Python and Jupyter'

.github/workflows/cd.yml

@@ -40,17 +40,17 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: executed-notebooks
-          path: build/jupyter_execute/recipes
+          path: build/jupyter_execute/
           if-no-files-found: error
 
       - name: Prepare for Jupyter Lite
         run: |
-          cp README.md docs/recipes/
+          cp README.md docs/
           # Convert Jupytext to ipynb format.
           pixi run ./convert_all.sh ipynb
 
       - name: Build Jupyter Lite
-        run: pixi run -e jupyterlite jupyter lite build --contents docs/recipes --output-dir build/html/jupyterlite
+        run: pixi run -e jupyterlite jupyter lite build --contents docs/ --output-dir build/html/jupyterlite
 
       - name: Upload HTML as GitHub artifact
         uses: actions/upload-pages-artifact@v3

convert_all.sh

@@ -10,10 +10,10 @@ fi
 error_occurred=0
 
 if [ "$1" = "ipynb" ]; then
-    files=$(find docs/recipes/ -name "*.md" | grep -v .ipynb_checkpoints)
+    files=$(find docs/ -name "*.md" | grep -v .ipynb_checkpoints)
     for file in $files; do
         # Extract the kernel information from the Jupytext Markdown file
-        kernel_info=$(grep -A 10 '^---$' "$file" | grep -E 'kernelspec')
+	kernel_info=$(head -n 15 "$file" | grep -A 10 '^---$' | grep -E 'kernelspec')
         # Skip if no kernel information was found
         if [ -z "$kernel_info" ]; then
             continue
@@ -27,7 +27,7 @@ if [ "$1" = "ipynb" ]; then
         fi
     done
 elif [ "$1" = "md" ]; then
-    files=$(find docs/recipes/ -name "*.ipynb" | grep -v .ipynb_checkpoints)
+    files=$(find docs/ -name "*.ipynb" | grep -v .ipynb_checkpoints)
     for file in $files; do
         jupytext --to markdown "$file" && rm "$file"
         if [ $? -ne 0 ]; then

docs/contributing.md

@@ -28,24 +28,25 @@ git clone [email protected]:bluesky/bluesky-cookbook
 
 ## Overview
 
-Each "recipe" is a directory under `docs/recipes/tutorials/` or
-`docs/recipes/how-to/`. It may contain one or more Markdown (`.md`) files with
-a mixture of narrative text and code. Each recipe directory may also contain
-supporting data files, scripts, illustrations, solutions to exercises, etc.
+Each "recipe" is a directory under `docs/tutorials/` or `docs/how-to/`. It may
+contain one or more Markdown (`.md`) files with a mixture of narrative text and
+code. Each recipe directory may also contain supporting data files, scripts,
+illustrations, solutions to exercises, etc.
 
 ```none
 $ tree docs/
 docs/
 ├── conf.py
 ├── contributing.md
 ├── index.md
-├── recipes
-│   ├── tutorials
-│   │   ├── getting-started
-│   │   │   └── hello-bluesky.md
-│   │   ├── flyscanning
-│   │   │   └── basic-demo.md
-│   ├── how-to
+├── tutorials
+│   ├── getting-started
+│   │   └── hello-bluesky.md
+│   ├── flyscanning
+│   │   └── basic-demo.md
+├── how-to
+│   ├── deploy
+│   │   └── single-process.md
 ...
 ```
 
@@ -90,13 +91,12 @@ Open `build/html/index.html` in a web browser.
 pixi run jupyter lab
 ```
 
-In the file browser, locate one of the examples under `docs/recipes/`. Double
-click to open.
+In the file browser, locate one of the examples under `docs/tutorials/` or
+`docs/how-to/`. Double click to open the directory.
 
-Files like `docs/recipes/static/static.md` are plain Markdown files. Files like
-`docs/recipes/executable/basics.md` have a YAML header which enables the
-documentation build system to convert them to Jupyter notebooks and execute
-them:
+Files like `docs/tutorial/getting-started/hello-bluesky.md` have a YAML header
+which enables the documentation build system to convert them to Jupyter
+notebooks and execute them:
 
 ```yaml
 ---
@@ -132,7 +132,7 @@ The script `test.sh` runs files with executable code from top to bottom and
 prints any unexpected tracebacks.
 
 ```
-pixi run ./test.sh docs/recipes/executable/basics.md
+pixi run ./test.sh docs/tutorials/getting-started/hello-bluesky.md
 ```
 
 `````{note}
@@ -171,5 +171,5 @@ Once changes are merged to the `main` branch, the GitHub Actions [Publish workfl
   where users need to be handed Jupyter Notebook files directly, such as Google
   Colab.
 
-[notebooks-branch]: https://github.com/bluesky/bluesky-cookbook/tree/notebooks/docs/recipes
+[notebooks-branch]: https://github.com/bluesky/bluesky-cookbook/tree/notebooks/
 [Publish workflow]: https://github.com/bluesky/bluesky-cookbook/actions/workflows/cd.yml

docs/how-to.md

@@ -0,0 +1,6 @@
+# How-to Guides
+
+```{toctree}
+:maxdepth: 2
+how-to/example/
+```

docs/how-to/example.md

@@ -0,0 +1,6 @@
+# Example
+
+```{toctree}
+:glob:
+example/*
+```

docs/index.md

@@ -1,10 +1,9 @@
 # Bluesky Cookbook
 
 ```{toctree}
-:maxdepth: 1
-:glob:
-recipes/tutorials.md
-recipes/how-to.md
+:maxdepth: 2
+tutorials
+how-to
 glossary
 contributing
 ```

docs/tutorials.md

@@ -0,0 +1,10 @@
+# Tutorials
+
+```{toctree}
+:maxdepth: 2
+:glob:
+tutorials/getting-started/
+tutorials/flyscanning/
+```
+
+Test 4

docs/tutorials/flyscanning.md

@@ -0,0 +1,6 @@
+# Flyscanning
+
+```{toctree}
+:glob:
+flyscanning/*
+```

docs/tutorials/flyscanning/basics.md

@@ -0,0 +1,16 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.16.4
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+# Flyscanning Basics
+
+TODO

docs/tutorials/getting-started.md

@@ -0,0 +1,6 @@
+# Getting Started
+
+```{toctree}
+:glob:
+getting-started/*
+```

docs/tutorials/getting-started/hello-bluesky.md

@@ -0,0 +1,16 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.16.4
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+# Hello Bluesky
+
+TODO