Scarfski/filament
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: format docs_src/README.md

Browse Source 
to trigger a docs regen
This commit is contained in:
Powei Feng
2026-03-25 22:59:46 -07:00
parent 31d447fec4
commit 7a869e7c01
1 changed files with 38 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
docs_src/README.md
View File

@@ -44,8 +44,8 @@ of markdown files that are then processed with `mdBook`.
The [github landing page] for Filament displays an extensive introduction to Filament. It
links to `BUILDING.md` and `CONTRIBUTING.md`, which are conventional pages for building or
contributing to the project. We copy these pages from their respective locations in the project
tree into `docs_src/src_mdbook/src/dup`. Moreover, to restore valid linkage between the pages, we need
to perform a number of URL replacements in addition to the copy. These replacements are
tree into `docs_src/src_mdbook/src/dup`. Moreover, to restore valid linkage between the pages,
we need to perform a number of URL replacements in addition to the copy. These replacements are
described in [`docs_src/build/duplicates.json`].
### Core concept docs
@@ -59,39 +59,57 @@ documents are written in [`markdeep`]. To embed them into our book, we
We describe step 1 in detail for the sake of record:
- Start a local-only server to serve the markdeep file (e.g. `Filament.md.html`)
- Start a `selenium` driver (essentially run chromium in headless mode)
- Visit the local page through the driver (i.e. open url `http://localhost:xx/Filament.md.html?export`)
- Visit the local page through the driver (i.e. open url
`http://localhost:xx/Filament.md.html?export`)
- Parse out the exported output in the retrieved html (note that the output of the markdeep
export is an html with the output captured in a `<pre>` tag).
- Replace css styling in the exported output as needed (so they don't interfere with the book's css.
- Replace css styling in the exported output as needed (so they don't interfere with the
book's css.
- Replace resource urls to refer to locations relative to the mdbook structure.
Any `markdeep` doc can be placed in `docs_src/src_markdeep/` and they will be parsed to html and included
in the book as above.
Any `markdeep` doc can be placed in `docs_src/src_markdeep/` and they will be parsed to html and
included in the book as above.
### READMEs
Filament depends on a number of libraries, which reside in the directory `libs`. These individual
libaries often have README.md in their root to describe itself. We collect these descriptions into our
book. In addition, client usage of Filament also requires using a set of binary tools, which are
located in `tools`. Some of tools also have README.md as description. We also collect them into the book.
libaries often have README.md in their root to describe itself. We collect these descriptions into
our book. In addition, client usage of Filament also requires using a set of binary tools, which are
located in `tools`. Some of tools also have README.md as description. We also collect them into the
book.
The process for copying and processing these READMEs is outlined in [Introductory docs](#introductory-doc).
The process for copying and processing these READMEs is outlined in
[Introductory docs](#introductory-doc).
### Web Examples and Tutorials
Filament provides a number of WebGL tutorials and examples in the `web/` directory. These are compiled during the WebGL CMake build and are integrated into the documentation via `duplicates.json`. The process is entirely automated:
1. `run.py` maps the `.html` and `.md` WebGL outputs from the `out/cmake-webgl-release/...` directory into `docs_src/src_mdbook/src/samples/web/` using the instructions in `duplicates.json`.
2. While transferring `.html` to `.md`, `run.py` strips away the `<!DOCTYPE html>`, `<head>`, and `<html>` tags. By retaining only the `<style>` and `<body>` elements, the HTML samples can be embedded cleanly into the `mdbook` site template without corrupting the DOM. It additionally collapses double-newlines (`\n\n`) because Markdown parsers will mistakenly fragment and wrap multi-line HTML tags into `<p>` blocks.
3. After `mdbook build` concludes, `docs_src/build/copy_web_docs.py` is invoked. This script creates `web/lib` and `web/assets` directories inside the final `book/` output directory, copying in the compiled WebAssembly engine (`filament.wasm`/`filament.js`) and any necessary assets (`.filamat`, `.glb`, `.ktx`, etc.).
4. Finally, `copy_web_docs.py` performs a regex pass over all HTML pages in `book/samples/web/` and `book/remote/` to rewrite their inline resource URLs to securely point to the shared `web/lib` and `web/assets` directories. It also dynamically overrides the `asset.loadResources()` Javascript call with an absolute URL (`new URL(..., window.location.href)`) so that `.glb`/`.gltf` assets fetch their internal `.bin` chunks correctly.
Filament provides a number of WebGL tutorials and examples in the `web/` directory. These are
compiled during the WebGL CMake build and are integrated into the documentation via
`duplicates.json`. The process is entirely automated:
1. `run.py` maps the `.html` and `.md` WebGL outputs from the `out/cmake-webgl-release/...`
directory into `docs_src/src_mdbook/src/samples/web/` using the instructions in `duplicates.json`.
2. While transferring `.html` to `.md`, `run.py` strips away the `<!DOCTYPE html>`, `<head>`, and
`<html>` tags. By retaining only the `<style>` and `<body>` elements, the HTML samples can be
embedded cleanly into the `mdbook` site template without corrupting the DOM. It additionally
collapses double-newlines (`\n\n`) because Markdown parsers will mistakenly fragment and wrap
multi-line HTML tags into `<p>` blocks.
3. After `mdbook build` concludes, `docs_src/build/copy_web_docs.py` is invoked. This script creates
`web/lib` and `web/assets` directories inside the final `book/` output directory, copying in the
compiled WebAssembly engine (`filament.wasm`/`filament.js`) and any necessary assets
(`.filamat`, `.glb`, `.ktx`, etc.).
4. Finally, `copy_web_docs.py` performs a regex pass over all HTML pages in `book/samples/web/` and
`book/remote/` to rewrite their inline resource URLs to securely point to the shared `web/lib` and
`web/assets` directories. It also dynamically overrides the `asset.loadResources()` Javascript call
with an absolute URL (`new URL(..., window.location.href)`) so that `.glb`/`.gltf` assets fetch
their internal `.bin` chunks correctly.
### 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_mdbook/src/notes` directory. No additional
processing is needed for these documents.
Filament source tree. We collect them into the `docs_src/src_mdbook/src/notes` directory. No
additional 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 or components (for example, the remote page for Android's `gltf_viewer`). These
files are stored in `docs_src/src_raw`.
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
To add any documentation, first consider the type of the document you like to add. If it