Docs: Refactor site navigation bar #12289

manuzhang · 2025-02-16T14:56:31Z

Relevant thread on devlist:

https://lists.apache.org/thread/jnfnf886r4y8q3og668f02pbw8ym7pq6

Fokko · 2025-02-17T08:42:52Z

site/docs/terms.md

 # Terms

-### Snapshot
+## Catalog


I like this, the catalog.md was always a bit lonely as it was the only concepts page.

I actually favor a little more on keeping catalog.md as a separate page, as the content is more than just terms. just keep this page in the new Specification section. Catalog is an important concept and deserves more details that the content page captured than simple term definition.

I agree catalogs deserve more details but having both catalogs and terms looks confusing to me. Isn't catalog a term?

agree that catalog is a term, which is good to be clarified in the terms page. but the content also talked a lot more about implementations. anyway, I can go either way on this one.

nit: what about taking Catalog one level up?

Currently its the first subtab under "Terms". Would it make sense to make it its on sub in "Specification"?

Fokko · 2025-02-17T08:45:52Z

site/nav.yml

+    - AES GCM Stream spec: gcm-stream-spec.md
+    - REST Catalog Spec: https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/apache/iceberg/main/open-api/rest-catalog-open-api.yaml
+    - Implementation status: status.md
+    - Terms: terms.md


I would also be open to bringing this back to its original place. Now it is at the very bottom of the specs, but I think it is nice for folks to understand the concepts without plowing through the specs themselves. Curious to learn what others think.

Do you mean keeping it at Project tab while merging Catalog into it?
Actually, these terms are more or less explained in the table spec. Maybe it's valuable as additional references as part of Specification, more like a FAQ?

maybe Fokko meant moving the Terms page at the top of the Specification section. that would make sense to me.

Top sounds good to me

RussellSpitzer · 2025-02-17T18:23:42Z

I think this looks good, but I would request some screenshots of the changes on the PR to demonstrate the differences. I don't think they have to be kept up to date with the review, but it's good to see what we are committing as rendered.

manuzhang · 2025-02-18T04:30:08Z

Screenshots of the website after the change

Homepage

Project Tab

Specification Tab

kevinjqliu

LGTM! Thanks for improving the docs! 💯

I verified the changes by running make serve locally

kevinjqliu · 2025-02-18T16:57:46Z

site/nav.yml

👍
except for concepts/catalog.md, for which the content is merged into site/docs/terms.md, nothing else changed. The tabs are just moved around to under "Specification"

ok i also double checked that moving from one tab to another doesn't affect the URL.

For example, "Table Spec" is moved from under "Project" to under "Specification", but the URL is still /spec 👍

the only URL that changed (removed) is concepts/catalog

kevinjqliu · 2025-02-18T17:07:27Z

site/docs/terms.md

 # Terms

-### Snapshot
+## Catalog


nit: what about taking Catalog one level up?

Currently its the first subtab under "Terms". Would it make sense to make it its on sub in "Specification"?

stevenzwu · 2025-02-18T22:21:01Z

seems like we have enough approvals. I am going to merge this.

any other changes can be followed up separately.

thanks @manuzhang for the contribution and @RussellSpitzer @Fokko @kevinjqliu for the reviews

* Site: Learn More to point to Spark QuickStart Doc (apache#12272) * Build: Bump datamodel-code-generator from 0.27.2 to 0.28.1 (apache#12290) * Spark 3.5: Fix job description of RewriteTablePathSparkAction (apache#12282) * Build: Bump io.netty:netty-buffer from 4.1.117.Final to 4.1.118.Final (apache#12287) Bumps [io.netty:netty-buffer](https://github.com/netty/netty) from 4.1.117.Final to 4.1.118.Final. - [Commits](netty/netty@netty-4.1.117.Final...netty-4.1.118.Final) --- updated-dependencies: - dependency-name: io.netty:netty-buffer dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Build: Bump software.amazon.awssdk:bom from 2.30.16 to 2.30.21 (apache#12286) Bumps software.amazon.awssdk:bom from 2.30.16 to 2.30.21. --- updated-dependencies: - dependency-name: software.amazon.awssdk:bom dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * OpenAPI: Add overwrite option when registering a table (apache#12239) * OpenAPI: Add optional overwrite when registering table * simplify to overwrite * Add the article to the description Co-authored-by: Eduard Tudenhoefner <etudenhoefner@gmail.com> * Update generated python as well Signed-off-by: Hongyue Zhang <steveiszhy@gmail.com> * Fix import order --------- Signed-off-by: Hongyue Zhang <steveiszhy@gmail.com> Co-authored-by: Eduard Tudenhoefner <etudenhoefner@gmail.com> * Build: Bump mkdocs-material from 9.6.3 to 9.6.4 (apache#12284) Bumps [mkdocs-material](https://github.com/squidfunk/mkdocs-material) from 9.6.3 to 9.6.4. - [Release notes](https://github.com/squidfunk/mkdocs-material/releases) - [Changelog](https://github.com/squidfunk/mkdocs-material/blob/master/CHANGELOG) - [Commits](squidfunk/mkdocs-material@9.6.3...9.6.4) --- updated-dependencies: - dependency-name: mkdocs-material dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Core: Fix Enabling row-lineage during Create Table (apache#12307) * API: Reject unknown type for required fields and validate defaults (apache#12302) * API: Fix TestInclusiveMetricsEvaluator notStartsWith tests. (apache#12303) * Core: Add variant type support to utils and visitors (apache#11831) * Core: Fix CI: Update tests with UnknownType from required to optional (apache#12316) * Docs: Refactor site navigation bar (apache#12289) * Parquet: Implement Variant readers (apache#12139) * Docs: Add rewrite_table_path Spark Procedure (apache#12115) * Parquet: Fix errorprone warning (apache#12324) * Docs: Add Apache Amoro docs (apache#11966) * Parquet: Fix performance regression in reader init (apache#12305) * Core: Fallback to GET requests for namespace/table/view exists checks (apache#12314) Co-authored-by: Daniel Weeks <dweeks@apache.org> * Docs: Fix refs in Apache Amoro docs (apache#12332) * Revert "Core: Serialize `null` when there is no current snapshot (apache#11560)" (apache#12312) This reverts commit bf8d25f. * Parquet: Fix performance regression in reader init (apache#12305) (apache#12329) Co-authored-by: Bryan Keller <bryanck@gmail.com> * Checkstyle: Apply the same generic type naming rules to interfaces and classes (apache#12333) --------- Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: Hongyue Zhang <steveiszhy@gmail.com> Co-authored-by: Danica Fine <danica.fine@gmail.com> Co-authored-by: Manu Zhang <OwenZhang1990@gmail.com> Co-authored-by: Yuya Ebihara <ebyhry@gmail.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Hongyue/Steve Zhang <steveiszhy@gmail.com> Co-authored-by: Eduard Tudenhoefner <etudenhoefner@gmail.com> Co-authored-by: Tom Tanaka <43331405+tomtongue@users.noreply.github.com> Co-authored-by: Ryan Blue <blue@apache.org> Co-authored-by: Aihua Xu <aihuaxu@gmail.com> Co-authored-by: Fokko Driesprong <fokko@apache.org> Co-authored-by: ConradJam <jam.gzczy@gmail.com> Co-authored-by: Bryan Keller <bryanck@gmail.com> Co-authored-by: Daniel Weeks <dweeks@apache.org> Co-authored-by: pvary <peter.vary.apache@gmail.com>

github-actions bot added the docs label Feb 16, 2025

manuzhang requested review from RussellSpitzer and stevenzwu February 16, 2025 14:59

manuzhang force-pushed the refactor-nav branch from e968c17 to 6aa5e42 Compare February 17, 2025 07:51

Fokko reviewed Feb 17, 2025

View reviewed changes

Docs: Refactor site navigation bar

3c5a73a

manuzhang force-pushed the refactor-nav branch from 6aa5e42 to 3c5a73a Compare February 18, 2025 04:23

stevenzwu approved these changes Feb 18, 2025

View reviewed changes

kevinjqliu approved these changes Feb 18, 2025

View reviewed changes

RussellSpitzer approved these changes Feb 18, 2025

View reviewed changes

stevenzwu merged commit 5e1ce86 into apache:main Feb 18, 2025
2 checks passed

manuzhang deleted the refactor-nav branch May 7, 2025 15:47

Docs: Refactor site navigation bar #12289

Docs: Refactor site navigation bar #12289

Uh oh!

Conversation

manuzhang commented Feb 16, 2025 • edited by Fokko Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manuzhang Feb 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RussellSpitzer commented Feb 17, 2025

Uh oh!

manuzhang commented Feb 18, 2025

Homepage

Project Tab

Specification Tab

Uh oh!

kevinjqliu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevenzwu commented Feb 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

manuzhang commented Feb 16, 2025 •

edited by Fokko

Loading

manuzhang Feb 17, 2025 •

edited

Loading

stevenzwu commented Feb 18, 2025 •

edited

Loading