Documentation

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

How the book is created and updated

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

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

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

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 phyiscally-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.

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