From e89363751d50962e98350d31c86995ba14bf9e2a Mon Sep 17 00:00:00 2001 From: Powei Feng Date: Fri, 18 Jul 2025 14:00:25 -0700 Subject: [PATCH] docs: various updates and improvements (#8971) - Add github link to page - Fix link in contributing.md - Small update to docs_src/README.md - Remove logo in the core docs - Move branching.md and release_guide.md to /docs_src - Add "under construction" warning for the web samples - Update matdbg README.md --- docs_src/README.md | 6 +-- docs_src/build/duplicates.json | 5 ++- docs_src/build/run.py | 4 ++ docs_src/src_mdbook/book.toml | 6 ++- docs_src/src_mdbook/src/SUMMARY.md | 2 + .../src_mdbook/src/images}/branching.png | Bin .../src_mdbook/src/notes/branching.md | 4 +- .../src_mdbook/src/notes/release_guide.md | 0 docs_src/src_mdbook/src/notes/versioning.md | 2 +- docs_src/src_mdbook/src/samples/web.md | 4 +- docs_src/src_mdbook/theme/index.hbs | 5 ++- libs/matdbg/README.md | 42 ++++-------------- 12 files changed, 35 insertions(+), 45 deletions(-) rename {art/diagrams => docs_src/src_mdbook/src/images}/branching.png (100%) rename BRANCHING.md => docs_src/src_mdbook/src/notes/branching.md (95%) rename RELEASE_GUIDE.md => docs_src/src_mdbook/src/notes/release_guide.md (100%) diff --git a/docs_src/README.md b/docs_src/README.md index e95e53cb7f..94c7a84627 100644 --- a/docs_src/README.md +++ b/docs_src/README.md @@ -76,11 +76,11 @@ The process for copying and processing these READMEs is outlined in [Introductor ### 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/notes` directory. No additional -processing are needed for these documents. +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/components (for example, the remote page for Android gltf_viewer). These +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 diff --git a/docs_src/build/duplicates.json b/docs_src/build/duplicates.json index d671379912..636115795d 100644 --- a/docs_src/build/duplicates.json +++ b/docs_src/build/duplicates.json @@ -12,7 +12,10 @@ "dest": "dup/building.md" }, "CONTRIBUTING.md": { - "dest": "dup/contributing.md" + "dest": "dup/contributing.md", + "link_transforms": { + "/CODE_STYLE.md": "code_style.md" + } }, "CODE_STYLE.md": { "dest": "dup/code_style.md" diff --git a/docs_src/build/run.py b/docs_src/build/run.py index 3337715bea..d7decd247b 100644 --- a/docs_src/build/run.py +++ b/docs_src/build/run.py @@ -114,12 +114,16 @@ def pull_markdeep_docs(): # 1. Remove the double empty lines. These make the following text seem like markdown text as oppose to embedded html. # 2. Remove the max-width styling from the body tag. # 3. Remove the font-family styling from the body tag. + # 4. Properly redirect images to the right directory text = text.replace("\n\n","\n")\ .replace("max-width:680px;", "")\ .replace("font-family:Palatino", "--font-family:Palatino")\ .replace("\"./images", "\"../images")\ .replace("\"images/", "\"../images/") + # 5. Remove giant filament logo + text = '\n'.join([l for l in text.split("\n") if 'filament_logo.png' not in l]) + # Save the page source as .md with embedded html with open(f'{MAIN_DIR}/{doc.lower()}.md', "w", encoding="utf-8") as f: f.write(text) diff --git a/docs_src/src_mdbook/book.toml b/docs_src/src_mdbook/book.toml index feca08db22..7d9ae47533 100644 --- a/docs_src/src_mdbook/book.toml +++ b/docs_src/src_mdbook/book.toml @@ -10,8 +10,10 @@ create-missing = false [output.html] mathjax-support = true -default-theme = "ayu" -preferred-dark-theme = "ayu" +default-theme = "light" +preferred-dark-theme = "light" +git-repository-url = "https://github.com/google/filament" +git-repository-icon = "fa-github" [output.html.print] enable = false diff --git a/docs_src/src_mdbook/src/SUMMARY.md b/docs_src/src_mdbook/src/SUMMARY.md index 168bac5f9a..b61e9cde06 100644 --- a/docs_src/src_mdbook/src/SUMMARY.md +++ b/docs_src/src_mdbook/src/SUMMARY.md @@ -13,6 +13,8 @@ - [Web Tutorial](./samples/web.md) - [Technical Notes](./notes/README.md) - [Versioning](./notes/versioning.md) + - [Branching](./notes/branching.md) + - [Release Guide](./notes/release_guide.md) - [Documentation](./dup/docs.md) - [Debugging](./notes/debugging.md) - [Metal](./notes/metal_debugging.md) diff --git a/art/diagrams/branching.png b/docs_src/src_mdbook/src/images/branching.png similarity index 100% rename from art/diagrams/branching.png rename to docs_src/src_mdbook/src/images/branching.png diff --git a/BRANCHING.md b/docs_src/src_mdbook/src/notes/branching.md similarity index 95% rename from BRANCHING.md rename to docs_src/src_mdbook/src/notes/branching.md index cf15e12754..578938dc24 100644 --- a/BRANCHING.md +++ b/docs_src/src_mdbook/src/notes/branching.md @@ -1,4 +1,6 @@ -![Filament branching strategy](art/diagrams/branching.png) +# Branching + +![Filament branching strategy](../images/branching.png) ## Which branch do I open my PR against? diff --git a/RELEASE_GUIDE.md b/docs_src/src_mdbook/src/notes/release_guide.md similarity index 100% rename from RELEASE_GUIDE.md rename to docs_src/src_mdbook/src/notes/release_guide.md diff --git a/docs_src/src_mdbook/src/notes/versioning.md b/docs_src/src_mdbook/src/notes/versioning.md index 5b2d43396c..ce8c551386 100644 --- a/docs_src/src_mdbook/src/notes/versioning.md +++ b/docs_src/src_mdbook/src/notes/versioning.md @@ -1,4 +1,4 @@ -## Versioning +# Versioning Filament uses a 3-number versioning scheme that superficially resembles a [semantic version](https://semver.org/) but is actually more interesting because of our material system. Here diff --git a/docs_src/src_mdbook/src/samples/web.md b/docs_src/src_mdbook/src/samples/web.md index 9f61c338a2..08acc90f6f 100644 --- a/docs_src/src_mdbook/src/samples/web.md +++ b/docs_src/src_mdbook/src/samples/web.md @@ -1,5 +1,7 @@ # Web Docs +## [This page is under construction. Links are not working at the moment] + ## tutorials 1. [Triangle Tutorial](tutorial_triangle.html) @@ -14,6 +16,4 @@ - [knotess](https://prideout.net/knotess/) ## other documentation - -- [JavaScript API reference](reference.html) - [WebGL Meetup Slides](https://prideout.net/slides/filawasm) (2018) diff --git a/docs_src/src_mdbook/theme/index.hbs b/docs_src/src_mdbook/theme/index.hbs index 4f8a40f97d..bfc9184d18 100644 --- a/docs_src/src_mdbook/theme/index.hbs +++ b/docs_src/src_mdbook/theme/index.hbs @@ -103,7 +103,7 @@