ContextQMD
Back to Filament

Documentation

docs_src/README.md

1.71.26.8 KB
Original Source

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.

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.

For example, if you are adding a general technical note, then you would