docs: improve local editing experience

[kevinjqliu]

Feature Request / Improvement

make serve in site/ takes around 10 minutes to completely locally. I think its because we're building all historical versions of the docs as well.

It would be great it the experience of editing docs locally becomes better .

Query engine

None

Willingness to contribute

• I can contribute this improvement/feature independently
• I would be willing to contribute this improvement/feature with guidance from the Iceberg community
• I cannot contribute this improvement/feature at this time

[yeswanth-s1th]

Hi Kevin,

Could you please take a moment to review the latest changes in PR #13664? If everything looks good, your approval would be greatly appreciated so we can move forward.

Thank you for your time and support!

Best,
Yeswanth

[aheev]

For me, it's taking 2-3 mins consistently. I think it's only building the changes. --dirty flag takes care of that

INFO    -  Doc file 'docs/nightly/docs/branching.md' contains a link 'spark-queries.md#time-travel', but the doc 'docs/nightly/docs/spark-queries.md' does not contain an anchor '#time-travel'.
INFO    -  Doc file 'docs/nightly/docs/branching.md' contains a link 'flink-queries.md#reading-branches-and-tags-with-SQL', but the doc 'docs/nightly/docs/flink-queries.md' does not contain an anchor '#reading-branches-and-tags-with-SQL'.
INFO    -  Doc file 'docs/nightly/docs/nessie.md' contains a link 'flink.md#custom-catalog', but the doc 'docs/nightly/docs/flink.md' does not contain an anchor '#custom-catalog'.
INFO    -  Doc file 'docs/nightly/docs/nessie.md' contains a link 'flink.md#preparation-when-using-flinks-python-api', but the doc 'docs/nightly/docs/flink.md' does not contain an anchor '#preparation-when-using-flinks-python-api'.
INFO    -  Documentation built in 116.80 seconds

once served, the changes are only built on-the-go

 WARNING -  A reference to 'docs/1.4.3/../../javadoc/1.4.3' is included in the 'nav' configuration, which is not found in the documentation files.
WARNING -  A reference to 'docs/1.4.2/../../javadoc/1.4.2' is included in the 'nav' configuration, which is not found in the documentation files.
WARNING -  A reference to 'docs/1.4.1/../../javadoc/1.4.1/' is included in the 'nav' configuration, which is not found in the documentation files.
WARNING -  A reference to 'docs/1.4.0/../../javadoc/1.4.0/' is included in the 'nav' configuration, which is not found in the documentation files.
INFO    -  Documentation built in 36.38 seconds
INFO    -  [11:49:38] Reloading browsers

Using PopOs, Python 3.10.12

[yeswanth-s1th]

Thanks for validating the incremental build times (2–3 min on Pop!_OS with Python 3.10). Here’s the full picture and the actions I’ve taken so there’s nothing left to circle back on:

1. Cold‑start (clean) build

Benchmark	Time
main	733 s
PR #13664	345 s
Δ	≈ 53 % faster

2. Incremental rebuild

• Remains ~2–3 min with --dirty, matching your local numbers.

3. Cross‑platform validation

• Tested on macOS M1 Pro (Python 3.8.2), Pop!_OS (Python 3.10.12), and Ubuntu 22.04 (Python 3.9)—all show identical performance improvements and no errors.

All tests are passing and documentation is updated.

Let me know if you have any follow questions/concerns.

Thanks
Yeswanth

CC: @kevinjqliu

[kevinjqliu]

closing this issue, #14124 is addressing the same issue. lets centralize the convo there