Filament's documentation (which you are reading) is a collection of pages created with mdBook.

• 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

  python3 -m venv venv . venv/bin/activate

  After that you may install deps and run the build script.
• selenium package for python

  python3 -m pip install selenium

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

cd docs_src python3 build/run.py

docs is the github-specfic directory for producing a web frontend (i.e. documentation) for a project.

(To be completed)

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.

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.

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.

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.

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.

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.

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

• 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 section