| commit | ddce65c483deae73d2c10e01bf3c249983025a1c | [log] [tgz] |
|---|---|---|
| author | Wing Yew Poon <wypoon@gmail.com> | Tue Jun 07 08:19:47 2022 -0700 |
| committer | GitHub <noreply@github.com> | Tue Jun 07 08:19:47 2022 -0700 |
| tree | 03175c48848dd0c27d203023a61566889eacaaa3 | |
| parent | e3b7f2f6295d80f54fdf9c98b77a24f2322bb8cf [diff] |
Update Spark section on inspecting tables. (#66) Using the SparkSessionCatalog to query metadata tables is possible in Spark 3.2.
This repository contains the documentation for Apache Iceberg. It's built with Hugo and hosted at https://iceberg.apache.org.
The Iceberg documentation site is actually constructed from two hugo sites. The first, is the landing page. The second site, is the documentation site which contains the full Iceberg documentation, including the javadoc. The landing page and documentation sites are completely self-contained in the ./landing-page and ./docs directories, respectively. The Javadocs are in the ./javadoc directory.
The documentation folder in the Iceberg repository contains all the markdown docs used by the website. The common subfolder contains contents used by the landing page. The versioned subfolder contains the contents different for each version.
During each new release, the release manager copies contents from the Iceberg repository to this docs repository and cuts a new version branch. Contents under common are copied to ./landing-page/contents/common here, and contents under versioned are copied to ./docs/contents/docs here. Javadocs generated from the release are copied to the javadoc directory.
Changes to the markdown contents should be submitted directly in the Iceberg repository.
Changes to the website appearance (e.g. HTML, CSS changes) should be submitted to this repository against the main branch.
Changes to the documentation of old Iceberg versions should be submitted to this repository against the specific version branch.
All issues related to the doc website should still be submitted to the Iceberg repository. The GitHub Issues feature of this repository is disabled.
Clone this repository to run the website locally:
git clone git@github.com:apache/iceberg-docs.git cd iceberg-docs
To start the landing page site locally, run:
cd landing-page && hugo serve
To start the documentation site locally, run:
cd docs && hugo serve
If you would like to see how the latest website looks based on the documentation in the Iceberg repository, you can copy docs to this repository by:
rm -rf docs/content/docs rm -rf landing-page/content/common cp -r <path to iceberg repo>/docs/versioned docs/content/docs cp -r <path to iceberg repo>/docs/common landing-page/content/common
If you'd like to scan for broken links, one available tool is linkcheck that can be found here.
The landing page site is automatically deployed to the root of the asf-site branch by the deploy-landing-page job in the deployment workflow. There is only a single version of the landing page site, and the deploy-landing-page job only runs on commits to the main branch.
The docs site is automatically deployed to the docs directory in the asf-site branch, into a sub-directory named after the branch where the commit occured. This is performed by the deploy-docs job in the deployment workflow. The job deploys the docs site on commits to any branch except main. A branch is maintained for each Iceberg version. If the job runs and the directory does not yet exist in the asf-site branch, it will be created.
Additionally, the contents of the javadoc directory is deployed to a javadoc/<branch_name> directory in the asf-site branch.
In ./docs/redirect/index.html, a redirect meta tag exists to forward /docs and /latest to /docs/latest.
asf-site Branch StructureThe asf-site branch structure is the following:
. ├── docs │ ├── 0.12.1 │ │ └── <Full Docs Site @0.12.1> │ ├── latest │ │ └── <Full Docs Site @latest> │ └── index.html <-- Includes a redirect to 0.12.1 which is the latest version ├── javadoc │ ├── 0.12.1 │ │ └── <Full javadoc site @0.12.1> │ └── latest │ └── <Full javadoc Site @latest> └── <Full Landing Page Site>
A non-main branch commit deploys the docs site into a new sub-directory in the asf-site branch‘s docs directory, as well as copies the javadoc directory into a new sub-directory in the asf-site branch’s javadoc directory.
A main branch commit deploys the landing page site only and overwrites the landing page site at the root of the asf-site branch.
Redirects within one of the two sites can easily be done using the aliases keyword in the YAML Front Matter. You can read more about this Hugo URL Management feature here.
For root level redirects that are outside of both sites, the ./redirects directory contains pages with redirect meta tags. These are all deployed at the root level of the asf-site branch by the Deploy redirects step in the deployment workflow.