You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by "MartijnVisser (via GitHub)" <gi...@apache.org> on 2026/02/11 12:44:45 UTC

[PR] [FLINK-39067][docs] Move Python documentation from Hugo to PyDocs [flink]

MartijnVisser opened a new pull request, #27586:
URL: https://github.com/apache/flink/pull/27586

   ## What is the purpose of the change
   
   Migrate Python-specific documentation pages from the main Hugo docs site into the Sphinx-based PyDocs (flink-python/docs/) as part of FLIP-561. This consolidates all Python documentation into a single cohesive location.
   
   ## Brief change log
   
   - Add user_guide/ section to PyDocs covering Table API, DataStream API, configuration, dependency management, debugging, metrics, FAQs, and Python REPL
   - Replace moved Hugo pages (English + Chinese) with redirect stubs to preserve backward-compatible URLs
   - Set up Sphinx i18n with gettext for Chinese translations, including populated .po files from existing Hugo Chinese content
   - Add language switcher component to PyDocs navbar
   - Use sphinx.ext.extlinks with FLINK_DOCS_BASE_URL env var for version-configurable cross-references to main Flink docs
   - Update CI docs.sh to build Chinese PyDocs into zh/ subdirectory
   - Add sphinx-intl to sphinx dependency group in pyproject.toml
   - Add Makefile targets for gettext and Chinese docs builds
   - Update .gitignore for locale build artifacts
   
   ## Verifying this change
   
   PyDocs (English + Chinese)
   
   ```
     cd flink-python
     pip install -e ".[sphinx]"
     cd docs
     make html-zh
     python -m http.server -d _build/html 8080
   ```
   
     Then open http://localhost:8080/ and check:
   
     - "User Guide" appears in the left nav
     - All pages render correctly (code blocks, tables, links)
     - :flinkdoc: links point to flink-docs-master
     - Language toggle in the top navbar switches between English and Chinese (/zh/)
   
   Hugo docs (redirects)
   
   ```
     cd docs
     git submodule update --init --recursive
     ./setup_hugo.sh
     ./setup_docs.sh
     ./build_docs.sh --skip-integrate-connector-docs
   ```
   
   Then at http://localhost:1313/ check:
   
     - "Python" section is gone from left nav under Flink APIs
     - "Python DataStream" section is gone under DataStream API
     - "Python REPL" is gone under Deployment > REPLs
     - "Python User-defined Functions" still appears under Table API > Functions (as a stub with a link to PyDocs)
     - Old URLs like /docs/dev/python/ redirect to /api/python/user_guide/
   
   ## Does this pull request potentially affect one of the following parts:
   
     - Dependencies (does it add or upgrade a dependency): (yes / **no**)
     - The public API, i.e., is any changed class annotated with `@Public(Evolving)`: (yes / **no**)
     - The serializers: (yes / **no** / don't know)
     - The runtime per-record code paths (performance sensitive): (yes / **no** / don't know)
     - Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: (yes / **no** / don't know)
     - The S3 file system connector: (yes / **no** / don't know)
   
   ## Documentation
   
     - Does this pull request introduce a new feature? (yes / **no**)
     - If yes, how is the feature documented? (**not applicable** / docs / JavaDocs / not documented)
   


-- 
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-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39067][docs] Move Python documentation from Hugo to PyDocs [flink]

Posted by "MartijnVisser (via GitHub)" <gi...@apache.org>.
MartijnVisser commented on PR #27586:
URL: https://github.com/apache/flink/pull/27586#issuecomment-3890299646

   @flinkbot run azure


-- 
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-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39067][docs] Move Python documentation from Hugo to PyDocs [flink]

Posted by "MartijnVisser (via GitHub)" <gi...@apache.org>.
MartijnVisser commented on PR #27586:
URL: https://github.com/apache/flink/pull/27586#issuecomment-3890956423

   @flinkbot run azure


-- 
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-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39067][docs] Move Python documentation from Hugo to PyDocs [flink]

Posted by "flinkbot (via GitHub)" <gi...@apache.org>.
flinkbot commented on PR #27586:
URL: https://github.com/apache/flink/pull/27586#issuecomment-3884255037

   <!--
   Meta data
   {
     "version" : 1,
     "metaDataEntries" : [ {
       "hash" : "a1c281b70ab267312e4aa98474506a277be751f5",
       "status" : "UNKNOWN",
       "url" : "TBD",
       "triggerID" : "a1c281b70ab267312e4aa98474506a277be751f5",
       "triggerType" : "PUSH"
     } ]
   }-->
   ## CI report:
   
   * a1c281b70ab267312e4aa98474506a277be751f5 UNKNOWN
   
   <details>
   <summary>Bot commands</summary>
     The @flinkbot bot supports the following commands:
   
    - `@flinkbot run azure` re-run the last Azure build
   </details>


-- 
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-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39067][docs] Move Python documentation from Hugo to PyDocs [flink]

Posted by "MartijnVisser (via GitHub)" <gi...@apache.org>.
MartijnVisser merged PR #27586:
URL: https://github.com/apache/flink/pull/27586


-- 
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-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [FLINK-39067][docs] Move Python documentation from Hugo to PyDocs [flink]

Posted by "awmatheson (via GitHub)" <gi...@apache.org>.
awmatheson commented on PR #27586:
URL: https://github.com/apache/flink/pull/27586#issuecomment-3917050612

   I made another patch for the build system so it can use uv and pip. Summary below. I sent you the patch separately.
   
      **Problem:** The current README instructs `pip install -e ".[sphinx]"` from `flink-python/`, but that tries to build the full flink-python package (including apache-beam) which fails on Python 3.12+ due
       to missing `pkg_resources`. The `flink-python/pyproject.toml` also has no `[project]` table, so `uv sync` doesn't work either.
   
      **Fix:** This patch adds a standalone `pyproject.toml` in `flink-python/docs/` with just the Sphinx dependencies, so the docs can be built independently:
   
      ```bash
      cd flink-python/docs
      uv sync
      make html
      ```
   
      The Makefile auto-detects `uv` on PATH and uses `uv run` to invoke Sphinx. If uv isn't available, it falls back to bare `sphinx-build` (the existing behavior). The `SPHINXBUILD` / `SPHINXPYTHON`
      overrides still work for CI or custom setups.
   
      Changes:
      - `docs/pyproject.toml` — new, with Sphinx deps in a `[dependency-groups] dev` group
      - `docs/uv.lock` — lockfile for reproducible installs
      - `docs/Makefile` — auto-detect uv, use `uv run` for sphinx-build/sphinx-intl/python
      - `docs/README.md` — updated prerequisites with uv (recommended) and pip fallback


-- 
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-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org