rdblue commented on code in PR #8659: URL: https://github.com/apache/iceberg/pull/8659#discussion_r1367526033
########## site/README.md: ########## @@ -0,0 +1,182 @@ +<!-- + - Licensed to the Apache Software Foundation (ASF) under one or more + - contributor license agreements. See the NOTICE file distributed with + - this work for additional information regarding copyright ownership. + - The ASF licenses this file to You under the Apache License, Version 2.0 + - (the "License"); you may not use this file except in compliance with + - the License. You may obtain a copy of the License at + - + - http://www.apache.org/licenses/LICENSE-2.0 + - + - Unless required by applicable law or agreed to in writing, software + - distributed under the License is distributed on an "AS IS" BASIS, + - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + - See the License for the specific language governing permissions and + - limitations under the License. + --> + +# Iceberg site and documentation + +This subproject contains the [MkDocs projects](https://www.mkdocs.org/) that define the non-versioned Iceberg site and the versioned Iceberg documentation. The Iceberg site MkDocs project contains a plugin that builds all the static sites for each version of documentation. These subsites are all weaved together to make the final Apache Iceberg site and docs with a single build. + +## Requirements + +* Python >=3.9 +* pip + + +## Usage + +The directory structure in this repository mimics the sitemap hierarchy of the website. This aims to help contributors find the source files needed to make their changes faster. To understand the layout and naming, it is helpful to have some basic understandings of the MkDocs framework defaults. + +### MkDocs background + +In MkDocs, the [`docs_dir`](https://www.mkdocs.org/user-guide/configuration/#docs_dir) points to the root directory containing the source markdown files for an MkDocs project. By default, this points to the `docs` directory. When you build MkDocs `mkdocs build`, MkDocs generates the static site in the [`site_dir`](https://www.mkdocs.org/user-guide/configuration/#site_dir) becomes the root of that project for the generated site. + +### Iceberg docs layout + +In the Iceberg docs, since the top-level site and versioned docs are contained in the same directory, they all live under the `/site` directory of the main Iceberg repository. The `/site/docs` directory is named this way to follow the [MkDocs convention](https://www.mkdocs.org/user-guide/configuration/#docs_dir), while the `/site/docs/docs` directory is an analog to the "Docs" navigation tab. Under this directory, you'll find the `/site/docs/docs/nightly` directory, which contains the state of the documentation in the local revisions. + +The non-versioned site pages are all the `/site/docs/.*md` files and the docs are the `/site/docs/docs/<version>/docs/*.md` files. Notice the location of the `mkdocs.yml`. Looking at this though, you may ask where the older versions and javadocs are. + +``` +./site/ +├── docs +│ ├── assets +│ ├── docs +│ │ └── nightly +│ │ ├── docs +│ │ │ ├── assets +│ │ │ ├── api.md +│ │ │ ├── ... +│ │ │ └── table-migration.md +│ │ └── mkdocs.yml (versioned) +│ ├── about.md +│ ├── ... +│ └── view-spec.md +├── README.md +├── mkdocs.yml (non-versioned) +├── requirements.txt +└── variables.yml +``` +### Building the versioned docs + +All previously versioned docs will be committed in `docs-<version>` branches and mounted using [git worktree](https://git-scm.com/docs/git-worktree) at build time. The worktree will pull these versions in following the `/site/docs/docs/<version>` convention. The `latest` version, will be a secondary copy of the most recent build version in the worktree, but pointing to `/site/docs/docs/latest`. There is also a `javadoc` branch that contains all prior static generation versions of the javadocs in a single tag. + +``` +./site/ +└── docs + ├── docs + │ ├── nightly + │ ├── latest + │ ├── 1.3.1 + │ ├── 1.3.0 + │ └── ... + └── javadoc + ├── latest + ├── 1.3.1 + ├── 1.3.0 + └── ... +``` + +### Install + +1. (Optional) Set up venv +``` +python -m venv mkdocs_env +source mkdocs_env/bin/activate +``` + +1. Install required Python libraries +``` +pip install -r requirements.txt +``` + +#### Adding additional versioned documentation + +To build locally with additional docs versions, add them to your working tree. +For now, I'm just adding a single version, and the javadocs directory. + +``` +git worktree add site/docs/docs/1.3.1 docs-1.3.1 +git worktree add site/docs/javadoc javadoc +``` + +## Build + +Run the build command in the root directory, and optionally add `--clean` to force MkDocs to clear previously generated pages. + +``` +mkdocs build [--clean] +``` + +## Run + +Start MkDocs server locally to verify the site looks good. + +``` +mkdocs serve +``` + +## Release process + +Deploying a version of the docs is a two step process: + 1. Cut a new release from the current branch revision. This creates a new branch `docs-<version>`,. + + ``` + .github/bin/deploy_docs.sh -v 1.4.0 Review Comment: We should move this to maybe a `dev` folder with scripts rather than `.github` which seems like an odd place for it. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org For additional commands, e-mail: issues-h...@iceberg.apache.org
