131 lines
6.8 KiB
Markdown
131 lines
6.8 KiB
Markdown
# Documentation
|
|
|
|
Filament's documentation (which you are reading) is a collection of pages created with [`mdBook`].
|
|
|
|
## How the book is created and updated {#how-to-create}
|
|
### Prerequisites
|
|
- Install [`mdBook`] for your platform
|
|
- There is a script `docs_src/build/install_mdbook.sh` that might help.
|
|
- It is best practice to install the python dependencies in a virtual python environment. You can
|
|
start such an environment by
|
|
```shell
|
|
python3 -m venv venv
|
|
. venv/bin/activate
|
|
```
|
|
After that you may install deps and run the build script.
|
|
- `selenium` package for python
|
|
```shell
|
|
python3 -m pip install selenium
|
|
```
|
|
|
|
### Generate {#how-to-generate}
|
|
We wrote a python script to gather and transform the different documents in the project tree into a
|
|
single book. This script can be found in [`docs_src/build/run.py`]. In addition,
|
|
[`docs_src/build/duplicates.json`] is used to describe the markdown files that are copied and
|
|
transformed from the source tree. These copies are placed into `docs_src/src_mdbook/src/dup`.
|
|
|
|
To collect the pages and generate the book, run the following
|
|
```shell
|
|
cd docs_src
|
|
python3 build/run.py
|
|
```
|
|
|
|
### Copy to `docs`
|
|
`docs` is the github-specfic directory for producing a web frontend (i.e. documentation) for a
|
|
project.
|
|
|
|
(To be completed)
|
|
|
|
## Document sources
|
|
We list the different document sources and how they are copied and processed into the collection
|
|
of markdown files that are then processed with `mdBook`.
|
|
|
|
### Introductory docs {#introductory-doc}
|
|
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
|
|
described in [`docs_src/build/duplicates.json`].
|
|
|
|
### Core concept docs
|
|
The primary design of Filament as a physically-based renderer and details of its materials
|
|
system are described in `Filament.md.html` and `Materials.md.html`, respectively. These two
|
|
documents are written in [`markdeep`]. To embed them into our book, we
|
|
1. Convert the markdeep into html
|
|
2. Embed the html output in a markdown file
|
|
3. Place the markdown file in `docs_src/src_mdbook/src/main`
|
|
|
|
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`)
|
|
- 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 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.
|
|
|
|
### 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.
|
|
|
|
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.
|
|
|
|
### 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.
|
|
|
|
### 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`.
|
|
|
|
## Adding more documents
|
|
To add any documentation, first consider the type of the document you like to add. If it
|
|
belongs to any of the above sources, then simply place the document in the appropriate place,
|
|
add a link in `SUMMARY.md`, and perform the steps outlined in
|
|
[how-to create section](#how-to-create).
|
|
|
|
For example, if you are adding a general technical note, then you would
|
|
- Place the document (file with extension `.md`) in `docs_src/src_mdbook/src/notes`
|
|
- Add a link in [`docs_src/src_mdbook/src/SUMMARY.md`]
|
|
- Run the commands in the [Generate](#how-to-generate) section
|
|
|
|
[github landing page]: https://google.github.io/filament
|
|
[`mdBook`]: https://rust-lang.github.io/mdBook/
|
|
[`markdeep`]: https://casual-effects.com/markdeep/
|
|
[`docs_src/build/run.py`]: https://github.com/google/filament/blob/main/docs_src/build/run.py
|
|
[`docs_src/build/duplicates.json`]: https://github.com/google/filament/blob/main/docs_src/build/duplicates.json
|
|
[`docs_src/src_mdbook/src/SUMMARY.md`]: https://github.com/google/filament/blob/main/docs_src/src_mdbook/src/SUMMARY.md
|