Doc fixes (#88)

* misc updates to docs and error msgs etc

* chore: formatting markdowns

Author: alphastrata

.gitignore

@@ -6,6 +6,9 @@ _deprecated
 *.gltf
 *.glb
 *.ktx2
+shaderbook
+bevy
+bevy_shaders
 
 # Generated by Cargo
 # will have compiled files and executables
@@ -23,9 +26,6 @@ target/
 .vscode
 .ruff_cache
 .pyc
-shaderbook
-bevy
-bevy_shaders
 .DS_Store# Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -17,13 +17,14 @@
 
 ## Our [bevy-shader-cheatsheet](bevy-shaders-cheatsheet.md#Contents)
 
-Shadplay is an app designed to help you learn `wgsl` with minimal friction, specifically for those wanting to learn `wgsl` to write shaders for bevy.
-The idea is to give one the minimal amount of bevy boilerplate etc., possible to get started writing \`wgsl\` ASAP, and provide a library of examples showing how some things are done, can be done etc.
+Shadplay is an app designed to help you learn `wgsl` with minimal friction, specifically for those wanting to learn `wgsl` to write shaders for [Bevy](https://bevyengine.org/).
 
 A secondary goal is to flesh out a relatively comprehensive 'port' of existing cool shader work from places like shadertoy etc -- because there's a few 'gotchas' around the differences in `glsl` and `wgsl` syntax, their respective builtins.
 
 A tertiary goal is to surface the builtins/existing library code that bevy's codebase provides.
 
+You will notice a large swath of the `wgsl` code from the Bevy codebase here, _we_ want it to be available to you and searchable (within your IDE) as, the `lsp` story for `wgsl` is not a great one... _yet_!.
+
 ______________________________________________________________________
 
 ### Why?
@@ -34,16 +35,16 @@ ______________________________________________________________________
 
 ## Features
 
-- A large collection of example shaders illustrating creative and educational uses. `assets/shaders/yourshadergoeshere.wgsl` specifically focusing on `wgsl`.
+- A large collection of example shaders illustrating creative and educational uses. `assets/shaders/yourshadergoeshere.wgsl`.
 - Live preview of shader code on bevy mesh geometry.
 - Textures, see `assets/shaders/howto-texture.wgsl`.
 - Drag and drop `.png` or `.jpg` files onto the window to use as said textures.
 - Mouse coords over a `uniform`, see `assets/shaders/howto-mouse.wgsl`.
 - Colour picker with system copy so that you get an immediate `vecf3(r, g, b)` immediately available for quick pasta action.
-- Drag and drop (valid `wgsl`) shaders onto the app.
-- Scripts to format your `wgsl` work, so it looks more rusty.
-- Scripts to pull _all_ the functions from the bevy codebase's shader code so you can easily lookup what's available for import.
-- Scripts to search the bevy source code (opening your browser) for specific keywords.
+- Drag and drop (valid `wgsl`) shaders onto the app window to see them working.
+- Tips and Tools to format your `wgsl` work, so it looks more rusty (which will help you quickly get up to speed with the existing `wgsl` in the Bevy codebase).
+- Scripts to pull _all_ the functions from the Bevy codebase's shader code so you can easily lookup what's available for import. (See `scripts/README.md`)
+- Scripts to search the Bevy source code (opening your browser) for specific keywords. (See `scripts/README.md`)
 - Continious image capture to create .gifs! (Currently only supporting a maximum framerate of 20FPS for capture.)
 - Automatic recompilation and update of shaders upon saving changes in your editor.
 - Quick iteration and experimentation with `wgsl` shader code.

build.rs

@@ -14,7 +14,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
             .expect("Failed to execute git clone command")
             .success()
     {
-        eprintln!("Failed to clone Bevy repository");
+        eprintln!("Failed to clone Bevy repository.\nShadplay makes a copy of the bevy codebase here to help generate documentation for you, if you don't want that modify _this_ file `./shadplay/build.rs`");
+
         exit(1);
     }
 

scripts/README.md

@@ -0,0 +1,29 @@
+# shadplay scripts
+
+```sh
+/scripts
+├── file-and-func.py
+├── make-gif-example.sh
+├── make-bevy-shaderdoc.py
+├── reset-2d.py
+├── reset-3d.py
+├── screenshots-to-gallery.py
+├── search-bevy-codebase-for.sh
+├── update-gallery.py
+└── wgsl-case-changer.py
+
+```
+
+| Script Name | Description |
+|-------------|-------------|
+| file_and_func.py |  This is a script that pulls the filenames/function pairings from the bevy sourcecode.
+| `file_and_func.py` |  This is a script that pulls the filenames/function pairings from the bevy sourcecode.
+|
+| `make-gif-example.sh` | Shows how one _may_ make a `.gif` from the output of gif-capture-mode, see main `../README.md` |
+| `make_bevy_shaderdoc.py` | creates a single markdown document with _**all**_ the Bevy codebase's `wgsl` |
+| `reset-2d.py` | Resets the 2d shader (useful if you want to try again from the default). |
+| `reset-3d.py` | Resets the 3d shader (useful if you want to try again from the default). |
+| `screenshots-to-gallery.py` | Moves shader screenshots you've created into markdown documents that pairs the code that generated them and said screenshot. |
+| `search-bevy-codebase-for.sh` | An example of something that may help you search the bevy codebase faster (if the shader doc generated by `make_bevy_shaderdoc.py` isn't helpful) |
+| `update-gallery.py` | updates the gallery's `README.md` |
+| `wgsl-case-changer.py` | go between `snake_case` and `CamelCase`, rusty

scripts/file_and_func.py scripts/file-and-func.py

@@ -5,14 +5,49 @@
 """
 
 import argparse
+import os
+import shutil
+import subprocess
 from pathlib import Path
 
 
+def move_to_shadplay():
+    current_dir = Path.cwd()
+    shadplay_dir = None
+
+    # Check if the current directory is already 'shadplay'
+    if current_dir.name == "shadplay":
+        print("Already in the 'shadplay' directory.")
+        return
+
+    # Search up the directory tree for 'shadplay'
+    for parent in current_dir.parents:
+        shadplay_dir = parent / "shadplay"
+        if shadplay_dir.exists():
+            print(f"Found 'shadplay' directory at: {shadplay_dir}")
+            break
+
+    # If not found, search down from the current directory
+    if not shadplay_dir or not shadplay_dir.exists():
+        for child in current_dir.iterdir():
+            if child.is_dir() and child.name == "shadplay":
+                shadplay_dir = child
+                print(f"Found 'shadplay' directory at: {shadplay_dir}")
+                break
+
+    # If 'shadplay' directory is found, change the current working directory to it
+    if shadplay_dir and shadplay_dir.exists():
+        os.chdir(shadplay_dir)
+        print(f"Moved to 'shadplay' directory: {shadplay_dir}")
+    else:
+        print("'shadplay' directory not found.")
+
+
 def collect_wgsl_contents(directory):
     wgsl_contents = {}
 
     # Recursively search for .wgsl files
-    for wgsl_file in directory.glob("**/*.wgsl"):
+    for wgsl_file in directory.rglob("*.wgsl"):
         # Extract the relative path without the file extension
         relative_path = wgsl_file.relative_to(directory).with_suffix("")
         with open(wgsl_file, "r") as file:
@@ -48,6 +83,32 @@ def write_to_markdown(wgsl_contents, output_path):
         write_wgsl_contents(markdown_file, wgsl_contents)
 
 
+def clone_bevy_codebase():
+    # Define the URL of the Bevy repository
+    repo_url = "https://github.com/bevyengine/bevy.git"
+
+    # Define the directory where you want to clone the repository
+    # This is set to a directory named 'bevy' in the current working directory
+    clone_dir = os.path.join(os.getcwd(), "bevy")
+
+    # Check if the directory already exists
+    if os.path.exists(clone_dir):
+        print(
+            f"The directory '{clone_dir}' already exists. To be certain you get the latest, we'll remove it and reclone the source.."
+        )
+        shutil.rmtree(clone_dir)
+        print(f"Directory '{clone_dir}' removed.")
+
+        clone_bevy_codebase()
+
+    # Use subprocess to run the git clone command
+    try:
+        subprocess.run(["git", "clone", repo_url, clone_dir], check=True)
+        print(f"Bevy codebase cloned successfully into '{clone_dir}'.")
+    except subprocess.CalledProcessError as e:
+        print(f"Failed to clone the Bevy codebase. Error: {e}")
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Convert .wgsl files to a markdown document."
@@ -61,12 +122,21 @@ def main():
     parser.add_argument(
         "--output",
         type=str,
-        default="bevy_shader_book.md",
-        help="Output markdown file (default: bevy_shader_book.md)",
+        default="bevy-shader-book.md",
+        help="Output markdown file (default: bevy-shader-book.md)",
+    )
+    parser.add_argument(
+        "--skip-clone", action="store_true", help="Skip cloning the Bevy codebase."
     )
 
     args = parser.parse_args()
 
+    move_to_shadplay()
+
+    # Skip cloning if the --skip-clone flag is set
+    if not args.skip_clone:
+        clone_bevy_codebase()
+
     input_directory = Path(args.input)
     output_path = Path(args.output)
 

scripts/make_bevy_shaderdoc.py scripts/make-bevy-shaderdoc.py

@@ -21,5 +21,5 @@
 search_query="$1"
 github_url="https://github.com/search?q=repo%3Abevyengine%2Fbevy+$search_query+language%3AWGSL&type=code&l=WGSL"
 
-# Open the URL in the default web browser
+# Open the URL in the default web browser (sorry, assumes linux/gnome users..)
 xdg-open "$github_url"