iceberg Spec: Fix table of content generation

Table of contents in the spec web page is not generated for spec and its subsection after https://github.com/apache/iceberg/pull/10948. It is super hard to navigate the spec without the table of contents.

The reason is mkdocs only consider first H1 for TOC generation. More info: https://github.com/squidfunk/mkdocs-material/issues/818

So, keeping spec as H2 and adjusted its sub topics. Note that the double # removal is not fully reverted, only added back one # . It is still kept at the same level as expected in the PR#10948

Also locally verified the new table of contents by building it in the site directory using make serve and hosted at http://localhost:8000/spec

Sep 02 '24 11:09 ajantha-bhat

I think this is probably a reasonable thing to do. Looking online, apparently switching to a single H1 element will also help out screen readers and accessibility software as well so sounds like a good thing to do. I would like to hear if anyone else has strong opnions though, especially since we have a few inflight Spec changes.

Sep 19 '24 21:09 RussellSpitzer

ping @rdblue

Sep 27 '24 05:09 ajantha-bhat

TOC with this change

Oct 15 '24 01:10 ajantha-bhat

@ajantha-bhat I feel like this has bounced back and forth on the levels, but we should be focused on getting the structure correct first and then addressing the ToC. This current version has Specification at the same level as its children, which is not correct.

L2/H2 should be:

## Format Versioning
## Goals
## Overview
## Specification
## Appendix A: Format-specific Requirements
## Appendix B: 32-bit Hash Requirements
## Appendix C: JSON serialization
## Appendix D: Single-value serialization
## Appendix E: Format version changes
## Appendix F: Implementation Notes

Everything else should be nested below.

Oct 15 '24 19:10 danielcweeks

@danielcweeks: Thanks for the feedback. I have updated it accordingly.

New TOC looks like this.

Oct 16 '24 03:10 ajantha-bhat

I think this is fine. @danielcweeks is the organization what you want?

Oct 19 '24 22:10 rdblue

@ajantha-bhat looks like we have conflicts. It would be good to get this in, but I don't think this section of the docs is tied to the 1.7.0 release.

Oct 24 '24 19:10 danielcweeks

@danielcweeks: Thanks for the review. Conflict was due to recent row-lineage merge. I have resolved it now. PR is ready.

Oct 25 '24 06:10 ajantha-bhat

Thanks @ajantha-bhat and @danielcweeks , @rdblue , @manuzhang and @amogh-jahagirdar for review

Oct 25 '24 20:10 RussellSpitzer