[SPARK-34437][SQL][DOCS] Update Spark SQL guide about the rebasing DS options and SQL configs

[MaxGekk]

What changes were proposed in this pull request?

In the PR, I propose to update the Spark SQL guide about the SQL configs that are related to datetime rebasing:

• spark.sql.parquet.int96RebaseModeInWrite
• spark.sql.parquet.datetimeRebaseModeInWrite
• spark.sql.parquet.int96RebaseModeInRead
• spark.sql.parquet.datetimeRebaseModeInRead
• spark.sql.avro.datetimeRebaseModeInWrite
• spark.sql.avro.datetimeRebaseModeInRead

Parquet options added by #31489:

• datetimeRebaseMode
• int96RebaseMode

and Avro options added by #31529:

• datetimeRebaseMode

Why are the changes needed?

To inform users about supported DS options and SQL configs.

Does this PR introduce any user-facing change?

No

How was this patch tested?

By generating the doc and manually checking:

$ SKIP_API=1 SKIP_SCALADOC=1 SKIP_PYTHONDOC=1 SKIP_RDOC=1 jekyll serve --watch

[SparkQA]

Test build #135150 has finished for PR 31564 at commit 4795e90.

• This patch passes all tests.
• This patch merges cleanly.
• This patch adds no public classes.

[SparkQA]

Kubernetes integration test starting
URL: https://amplab.cs.berkeley.edu/jenkins/job/SparkPullRequestBuilder-K8s/39731/

[SparkQA]

Kubernetes integration test status success
URL: https://amplab.cs.berkeley.edu/jenkins/job/SparkPullRequestBuilder-K8s/39731/

[MaxGekk]

@dongjoon-hyun @gengliangwang @cloud-fan @HyukjinKwon Could you review this PR, please.

[cloud-fan]

These options are for migration purposes (same as the legacy configs). Do we really need to mention them in the public doc? How about the migration guide?

[MaxGekk]

These options are for migration purposes (same as the legacy configs).

I believe the rebase configs were placed to the legacy namespace mistakenly because they can be used not only for migration from previous Spark versions but also for reading (and writing) files written by other systems/frameworks/libs. So, the configs will stay with us forever. I would like to propose to "rename" existing configs via:
ConfigBuilder has the method withAlternative , so, we can to introduce an alternative per each legacy rebase config:

spark.sql.legacy.parquet.int96RebaseModeInRead -> spark.sql.parquet.int96RebaseModeInRead

and deprecate

spark.sql.legacy.parquet.int96RebaseModeInRead

After that, document spark.sql.parquet.int96RebaseModeInRead in the Spark SQL guide.

[MaxGekk]

Since #31576 has been merged by @cloud-fan , I documented public configs here.

[SparkQA]

Test build #135203 has finished for PR 31564 at commit 773cb0b.

• This patch passes all tests.
• This patch merges cleanly.
• This patch adds no public classes.

[SparkQA]

Kubernetes integration test starting
URL: https://amplab.cs.berkeley.edu/jenkins/job/SparkPullRequestBuilder-K8s/39784/

[SparkQA]

Kubernetes integration test status success
URL: https://amplab.cs.berkeley.edu/jenkins/job/SparkPullRequestBuilder-K8s/39784/

[HyukjinKwon]

Do you plan to list other datasource options here? If not, I would write it as another section like Rebasing Datetime.

[MaxGekk]

Yes, other options should be here.

[HyukjinKwon]

Merged to master.