rdblue commented on code in PR #8659: URL: https://github.com/apache/iceberg/pull/8659#discussion_r1348089146
########## docs-new/README.md: ########## @@ -0,0 +1,175 @@ +<!-- + - 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 holds the static files that define and build the documentation site for Apache Iceberg. + +## Requirements + +* Python >=3.9 +* pip + + +## Usage + +The directory structure is intended to mimic the tree hierarchy of the website. This will enable contributors to find the documentation they need to update easier. The static and documentation will reside in the same location. + +All static pages are all the `./site/.*md` files and the docs are the `.site/docs/<version>/*.md` files. Notice the location of the `mkdocs.yml`. Looking at this though, you may ask where the older versions and javadocs are. + +``` +. +├── site +│ ├── assets +│ │ └── images +│ ├── docs +│ │ └── latest +│ │ ├── assets +│ │ ├── api.md +│ │ ├── aws.md +│ │ ├── branching.md +│ │ ├── ... +│ │ ├── **mkdocs.yml(docs)** +│ │ ├── ... +│ │ ├── spark-structured-streaming.md +│ │ ├── spark-writes.md +│ │ └── table-migration.md +│ ├── ASF.md +│ ├── about.md +│ ├── ... +│ ├── vendors.md +│ └── view-spec.md +├── LICENSE +├── README.md +├── **mkdocs.yml(static)** +├── requirements.txt +└── variables.yml +``` + +All of the documentation versions are saved in special `docs-<version>` branches that only contain the root of the docs version. There is also a `javadoc` tag that contains all prior versions of the javadocs in a single tag. These are generated and loaded only at build time using the [git-worktree](https://git-scm.com/docs/git-worktree) docs. + +``` +. +└── site + ├── docs + │ ├── 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/1.3.1 docs-1.3.1 +git worktree add site/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 `latest` documentation which creates a new branch `docs-<version>`. + + ``` + .github/bin/deploy_docs.sh -v 1.4.0 + ``` + + See [deploy_docs.sh](.github/bin/deploy_docs.sh) for more details. + + 1. Make sure to add the new version to the list of versions to pull into git worktree. + 1. Follow the steps in [the build process](#build). + 1. Push the generated site to `gh-pages`. Review Comment: This will eventually need to be the ASF branch. -- 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
