From b5b5dc2c04db1b1185ec8a1061ab50fe3efb8dde Mon Sep 17 00:00:00 2001 From: rutb327 Date: Mon, 4 Aug 2025 14:14:19 -0700 Subject: [PATCH 1/2] Added Nightly documentation --- .github/workflows/python-nightly-docs.yml | 85 +++++++++++++++++++++++ mkdocs/build-all.sh | 36 ++++++++++ mkdocs/docs/SUMMARY.md | 3 + mkdocs/docs/latest/mkdocs.yml | 68 ++++++++++++++++++ mkdocs/docs/nightly/mkdocs.yml | 68 ++++++++++++++++++ 5 files changed, 260 insertions(+) create mode 100644 .github/workflows/python-nightly-docs.yml create mode 100755 mkdocs/build-all.sh create mode 100644 mkdocs/docs/latest/mkdocs.yml create mode 100644 mkdocs/docs/nightly/mkdocs.yml diff --git a/.github/workflows/python-nightly-docs.yml b/.github/workflows/python-nightly-docs.yml new file mode 100644 index 0000000000..9632dd619d --- /dev/null +++ b/.github/workflows/python-nightly-docs.yml @@ -0,0 +1,85 @@ +# +# 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. +# +name: "Nightly Documentation" + +on: + schedule: + # Run at midnight UTC + - cron: '0 0 * * *' + workflow_dispatch: # Allow manual triggering + +jobs: + build-and-deploy: + runs-on: ubuntu-22.04 + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + cache: 'pip' + + - name: Install poetry + run: make install-poetry + + - name: Install documentation dependencies + run: make docs-install + + - name: Build documentation + run: | + cd mkdocs + ./build-all.sh + + - name: Deploy documentation + run: | + git config --global user.name 'GitHub Actions' + git config --global user.email 'actions@github.com' + + # Clone the gh-pages branch + git clone --single-branch --branch gh-pages https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} gh-pages-repo || { + git clone https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} gh-pages-repo + cd gh-pages-repo + git checkout --orphan gh-pages + git rm -rf . + echo "py.iceberg.apache.org" > CNAME + git add CNAME + git commit -m "Initialize gh-pages branch" + git push origin gh-pages + cd .. + } + + # Copy the built site (which contains both main and nightly) + rm -rf gh-pages-repo/* + cp -r mkdocs/site/* gh-pages-repo/ + touch gh-pages-repo/.nojekyll + + cd gh-pages-repo + git add --all + if ! git diff --staged --quiet; then + git commit -m "Update documentation with both main and nightly versions" + git push origin gh-pages + fi diff --git a/mkdocs/build-all.sh b/mkdocs/build-all.sh new file mode 100755 index 0000000000..ee648ce23a --- /dev/null +++ b/mkdocs/build-all.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +# +# 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. +# + +set -e + +echo "Cleaning previous builds" +rm -rf site + +echo "Building latest documentation" +cd docs/latest +poetry run mkdocs build --config-file mkdocs.yml +cd ../.. + +echo "Building nightly documentation" +cd docs/nightly +poetry run mkdocs build --config-file mkdocs.yml +cd ../.. + +echo "Documentation build complete" diff --git a/mkdocs/docs/SUMMARY.md b/mkdocs/docs/SUMMARY.md index c344b2fdd2..998893eefe 100644 --- a/mkdocs/docs/SUMMARY.md +++ b/mkdocs/docs/SUMMARY.md @@ -24,6 +24,8 @@ - [Configuration](configuration.md) - [CLI](cli.md) - [API](api.md) + - [Row Filter Syntax](row-filter-syntax.md) + - [Expression DSL](expression-dsl.md) - [Contributing](contributing.md) - [Community](community.md) - Releases @@ -32,6 +34,7 @@ - [Release Notes](https://github.com/apache/iceberg-python/releases) - [Nightly Build](nightly-build.md) - [Code Reference](reference/) +- [Nightly](https://py.iceberg.apache.org/nightly/) diff --git a/mkdocs/docs/latest/mkdocs.yml b/mkdocs/docs/latest/mkdocs.yml new file mode 100644 index 0000000000..47f59c7058 --- /dev/null +++ b/mkdocs/docs/latest/mkdocs.yml @@ -0,0 +1,68 @@ +# 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. +--- +site_name: PyIceberg +site_url: https://py.iceberg.apache.org/ +repo_url: "https://github.com/apache/iceberg-python" +repo_name: "apache/iceberg-python" + +plugins: + - gen-files: + scripts: + - ../../gen_doc_stubs.py + - literate-nav: + nav_file: SUMMARY.md + - search + - section-index + - mkdocstrings: + handlers: + python: + paths: [../../..] + +theme: + name: material + logo: ../../assets/images/iceberg-logo-icon.png + favicon: ../../assets/images/iceberg-logo-icon.png + font: + text: Lato + features: + - navigation.top + - navigation.tracking + - navigation.tabs + - navigation.tabs.sticky + palette: + - scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + +markdown_extensions: + - admonition + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + +docs_dir: ../../docs +site_dir: ../../site diff --git a/mkdocs/docs/nightly/mkdocs.yml b/mkdocs/docs/nightly/mkdocs.yml new file mode 100644 index 0000000000..87b9e48b06 --- /dev/null +++ b/mkdocs/docs/nightly/mkdocs.yml @@ -0,0 +1,68 @@ +# 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. +--- +site_name: PyIceberg +site_url: https://py.iceberg.apache.org/nightly/ +repo_url: "https://github.com/apache/iceberg-python" +repo_name: "apache/iceberg-python" + +plugins: + - gen-files: + scripts: + - ../../gen_doc_stubs.py + - literate-nav: + nav_file: SUMMARY.md + - search + - section-index + - mkdocstrings: + handlers: + python: + paths: [../../..] + +theme: + name: material + logo: ../../assets/images/iceberg-logo-icon.png + favicon: ../../assets/images/iceberg-logo-icon.png + font: + text: Lato + features: + - navigation.top + - navigation.tracking + - navigation.tabs + - navigation.tabs.sticky + palette: + - scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + +markdown_extensions: + - admonition + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + +docs_dir: ../../docs +site_dir: ../../site/nightly From 60acd0d9b5dee6d858d4639106446ea09b53b1b3 Mon Sep 17 00:00:00 2001 From: rutb327 Date: Tue, 5 Aug 2025 10:23:26 -0700 Subject: [PATCH 2/2] corrections --- .github/workflows/python-nightly-docs.yml | 36 +++-------------------- .github/workflows/python-release-docs.yml | 19 ++++-------- mkdocs/build-all.sh | 36 ----------------------- mkdocs/docs/nightly/mkdocs.yml | 2 +- 4 files changed, 10 insertions(+), 83 deletions(-) delete mode 100755 mkdocs/build-all.sh diff --git a/.github/workflows/python-nightly-docs.yml b/.github/workflows/python-nightly-docs.yml index 9632dd619d..d1baba89c9 100644 --- a/.github/workflows/python-nightly-docs.yml +++ b/.github/workflows/python-nightly-docs.yml @@ -25,7 +25,7 @@ on: workflow_dispatch: # Allow manual triggering jobs: - build-and-deploy: + build-and-deploy-nightly: runs-on: ubuntu-22.04 concurrency: group: ${{ github.workflow }}-${{ github.ref }} @@ -49,37 +49,9 @@ jobs: - name: Install documentation dependencies run: make docs-install - - name: Build documentation - run: | - cd mkdocs - ./build-all.sh - - - name: Deploy documentation + - name: Build and deploy nightly documentation run: | + cd mkdocs/docs/nightly git config --global user.name 'GitHub Actions' git config --global user.email 'actions@github.com' - - # Clone the gh-pages branch - git clone --single-branch --branch gh-pages https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} gh-pages-repo || { - git clone https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} gh-pages-repo - cd gh-pages-repo - git checkout --orphan gh-pages - git rm -rf . - echo "py.iceberg.apache.org" > CNAME - git add CNAME - git commit -m "Initialize gh-pages branch" - git push origin gh-pages - cd .. - } - - # Copy the built site (which contains both main and nightly) - rm -rf gh-pages-repo/* - cp -r mkdocs/site/* gh-pages-repo/ - touch gh-pages-repo/.nojekyll - - cd gh-pages-repo - git add --all - if ! git diff --staged --quiet; then - git commit -m "Update documentation with both main and nightly versions" - git push origin gh-pages - fi + mkdocs gh-deploy --remote-branch=gh-pages --config-file mkdocs.yml --remote-name origin --force --dir-name nightly diff --git a/.github/workflows/python-release-docs.yml b/.github/workflows/python-release-docs.yml index 2823563fe5..f355720fcb 100644 --- a/.github/workflows/python-release-docs.yml +++ b/.github/workflows/python-release-docs.yml @@ -35,22 +35,13 @@ jobs: run: make install-poetry - uses: actions/setup-python@v5 with: - python-version: ${{ matrix.python }} + python-version: 3.12 - name: Install docs run: make docs-install - - name: Build docs - run: make docs-build - - name: Copy - working-directory: ./mkdocs - run: mv ./site /tmp/site - - name: Push changes to gh-pages branch + - name: Deploy latest docs to gh-pages run: | - git checkout --orphan gh-pages-tmp - git rm --quiet -rf . - cp -r /tmp/site/* . + cd mkdocs/docs/latest git config --global user.name 'GitHub Actions' git config --global user.email 'actions@github.com' - echo "py.iceberg.apache.org" > CNAME - git add --all - git commit -m 'Publish Python docs' - git push -f origin gh-pages-tmp:gh-pages || true + echo "py.iceberg.apache.org" > ../../CNAME + mkdocs gh-deploy --remote-branch=gh-pages --config-file mkdocs.yml --force diff --git a/mkdocs/build-all.sh b/mkdocs/build-all.sh deleted file mode 100755 index ee648ce23a..0000000000 --- a/mkdocs/build-all.sh +++ /dev/null @@ -1,36 +0,0 @@ -#!/usr/bin/env bash -# -# 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. -# - -set -e - -echo "Cleaning previous builds" -rm -rf site - -echo "Building latest documentation" -cd docs/latest -poetry run mkdocs build --config-file mkdocs.yml -cd ../.. - -echo "Building nightly documentation" -cd docs/nightly -poetry run mkdocs build --config-file mkdocs.yml -cd ../.. - -echo "Documentation build complete" diff --git a/mkdocs/docs/nightly/mkdocs.yml b/mkdocs/docs/nightly/mkdocs.yml index 87b9e48b06..42402fd3e1 100644 --- a/mkdocs/docs/nightly/mkdocs.yml +++ b/mkdocs/docs/nightly/mkdocs.yml @@ -65,4 +65,4 @@ markdown_extensions: - pymdownx.superfences docs_dir: ../../docs -site_dir: ../../site/nightly +site_dir: ../../site