docs: various updates and improvements (#8971)

- Add github link to page
 - Fix link in contributing.md
 - Small update to docs_src/README.md
 - Remove logo in the core docs
 - Move branching.md and release_guide.md to /docs_src
 - Add "under construction" warning for the web samples
 - Update matdbg README.md

docs_src/README.md

@@ -76,11 +76,11 @@ The process for copying and processing these READMEs is outlined in [Introductor
 ### Other technical notes
 These are technical documents that do not fit into a library, tool, or directory of the
 Filament source tree. We collect them into the `docs_src/src/notes` directory. No additional
-processing are needed for these documents.
+processing is needed for these documents.
 
 ### Raw source files
-These are files that are not part of the mdbook generation, but should be included output in /docs
-to point to standalone pages/components (for example, the remote page for Android gltf_viewer). These
+These are files that are not part of the `mdbook` generation, but should be included output in `/docs`
+to point to standalone pages or components (for example, the remote page for Android's `gltf_viewer`). These
 files are stored in `docs_src/src_raw`.
 
 ## Adding more documents

docs_src/build/duplicates.json

@@ -12,7 +12,10 @@
         "dest": "dup/building.md"
     },
     "CONTRIBUTING.md": {
-        "dest": "dup/contributing.md"
+        "dest": "dup/contributing.md",
+        "link_transforms": {
+            "/CODE_STYLE.md": "code_style.md"
+        }
     },
     "CODE_STYLE.md": {
         "dest": "dup/code_style.md"

docs_src/build/run.py

@@ -114,12 +114,16 @@ def pull_markdeep_docs():
     # 1. Remove the double empty lines.  These make the following text seem like markdown text as oppose to embedded html.
     # 2. Remove the max-width styling from the body tag.
     # 3. Remove the font-family styling from the body tag.
+    # 4. Properly redirect images to the right directory
     text = text.replace("\n\n","\n")\
                .replace("max-width:680px;", "")\
                .replace("font-family:Palatino", "--font-family:Palatino")\
                .replace("\"./images", "\"../images")\
                .replace("\"images/", "\"../images/")
 
+    # 5. Remove giant filament logo
+    text = '\n'.join([l for l in text.split("\n") if 'filament_logo.png' not in l])
+
     # Save the page source as .md with embedded html
     with open(f'{MAIN_DIR}/{doc.lower()}.md', "w", encoding="utf-8") as f:
       f.write(text)

docs_src/src_mdbook/book.toml

@@ -10,8 +10,10 @@ create-missing = false
 
 [output.html]
 mathjax-support = true
-default-theme = "ayu"
-preferred-dark-theme = "ayu"
+default-theme = "light"
+preferred-dark-theme = "light"
+git-repository-url = "https://github.com/google/filament"
+git-repository-icon = "fa-github"
 
 [output.html.print]
 enable = false

docs_src/src_mdbook/src/SUMMARY.md

@@ -13,6 +13,8 @@
   - [Web Tutorial](./samples/web.md)
 - [Technical Notes](./notes/README.md)
   - [Versioning](./notes/versioning.md)
+    - [Branching](./notes/branching.md)
+    - [Release Guide](./notes/release_guide.md)
   - [Documentation](./dup/docs.md)
   - [Debugging](./notes/debugging.md)
     - [Metal](./notes/metal_debugging.md)

docs_src/src_mdbook/src/notes/branching.md

@@ -1,4 +1,6 @@
-![Filament branching strategy](art/diagrams/branching.png)
+# Branching
+
+![Filament branching strategy](../images/branching.png)
 
 ## Which branch do I open my PR against?
 

docs_src/src_mdbook/src/notes/versioning.md

@@ -1,4 +1,4 @@
-## Versioning
+# Versioning
 
 Filament uses a 3-number versioning scheme that superficially resembles a [semantic
 version](https://semver.org/) but is actually more interesting because of our material system. Here

docs_src/src_mdbook/src/samples/web.md

@@ -1,5 +1,7 @@
 # Web Docs
 
+## [This page is under construction. Links are not working at the moment]
+
 ## tutorials
 
 1. [Triangle Tutorial](tutorial_triangle.html)
@@ -14,6 +16,4 @@
 - [knotess](https://prideout.net/knotess/)
 
 ## other documentation
-
-- [JavaScript API reference](reference.html)
 - [WebGL Meetup Slides](https://prideout.net/slides/filawasm) (2018)

docs_src/src_mdbook/theme/index.hbs

@@ -103,7 +103,7 @@
         </script>
 
         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
-	    <div style="display:flex;align-items:center;justify-content:center">
+            <div style="display:flex;align-items:center;justify-content:center">
                 <img class="flogo" src="{{ path_to_root }}images/filament_logo_small.png"></img>
             </div>
             <!-- populated by js -->
@@ -126,6 +126,8 @@
                         <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                             <i class="fa fa-bars"></i>
                         </label>
+                        <!-- Filament: disable themes because the markdeep part does not look good for dark themes -->
+                        <!--
                         <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                             <i class="fa fa-paint-brush"></i>
                         </button>
@@ -136,6 +138,7 @@
                             <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                         </ul>
+                        -->
                         {{#if search_enabled}}
                         <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
                             <i class="fa fa-search"></i>

libs/matdbg/README.md

@@ -21,6 +21,7 @@ At the time of this writing, the following capabilities are supported.
 - OpenGL: Editing GLSL
 - Metal: Editing MSL
 - Vulkan: Editing transpiled GLSL, displaying disassembled SPIR-V
+- WebGPU: Editing WGSL
 
 Note that a given material can be built with multiple backends, even though only one backend
 is active in a particular session. For example, if the current app is using Vulkan, it is still
@@ -121,17 +122,18 @@ couple methods that are called from the Filament engine:
 
 ## JavaScript Client
 
-The web app is written in simple, modern JavaScript and avoids frameworks like React or Angular. It
-uses the following third-party libraries which are fetched from a CDN using `<script>`. This allows
-us to avoid adding them to our git repo, and leads to good caching behavior.
+The web app is written in simple, modern JavaScript. It uses third-party libraries
+which are fetched from a CDN using `<script>`. This allows us to avoid adding them to our git repo,
+and leads to good caching behavior.
 
-- **mustache** Popular tiny library that converts template strings into HTML.
+- **lit-html** A small wrapper around web-components for fast, iterative development.
 - **monaco** The engine behind Visual Studio Code.
     - We've configured this for C++ for somewhat reasonable syntax highlighting.
     - If desired we could extend the editor to better handle GLSL and SPIR-V.
 
-All the source code for our web app is contained in a single file (`script.js`) and the mustache
-template strings are specified using `<template>` tags in `index.html`.
+All the source code for our web app is contained in a single file (`app.js`), and there is a
+corresponding `api.js` to handle the protocol between the server (the running filament app) 
+the client (the browser).
 
 The web app basically provides a view over a pseudo-database which is a just a global variable
 that holds a dictionary that maps from material id's to objects that conform to the JSON described
@@ -219,38 +221,11 @@ used to create the SPIR-V is not available.
 
 ---
 
-## WebSocket messages
-
-Unlike HTTP requests, WebSocket messages can be pushed at any time and can travel in either
-direction. In our homegrown protocol, every WebSocket message starts with a command that matches
-\[A-Z\_]+ followed by a space character. Command arguments are delimited with spaces.
-
-Currently we support only one command. It travels from client to server.
-
-    EDIT [material id] [api index] [shader index] [shader length] [entire shader source....]
-
-The `material id` is 8 hex digits.
-
-The `api index` chooses between GL/VK/Metal and matches the values of the Backend enum (except that
-zero is invalid).
-
-The `shader index` is a zero-based index into the list of variants using the order that
-they appear in the package, where each API (GL / VK / Metal) has its own list.
-
-The `shader length` is the number of bytes required for UTF-8 encoding of the shader source string,
-not including the terminating null.
-
 ## Wish List
 
 - Allow editing of the original GLSL, perhaps by enhancing the `-g` option in matc and adding new chunk types.
-- Port the web side to TypeScript
-    - This will clarify the structure of the pseudo-database, which is currently a total hack.
-    - Allows us to use enums instead of strings in several places (e.g. getShaderAPI)
-    - Try using https://github.com/basarat/typescript-script because webpack etc is painful.
-    - If the above idea is too slow then use https://github.com/evanw/esbuild.
 - Expose the entire `engine.debug` struct in the web UI.
 - When shader errors occur, send them back over the wire to the web client.
-- Resizing the Chrome window causes layout issues.
 - The sidebar in the web app is not resizeable.
 - For the material ids, SHA-1 would be better than murmur since the latter can easily have collisions.
 - It would be easy to add diff decorations to the editor in our `onEdit` function:
@@ -265,4 +240,3 @@ not including the terminating null.
 [1]: https://github.com/civetweb/civetweb
 [2]: https://microsoft.github.io/monaco-editor/
 [3]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template
-[4]: https://mustache.github.io/