Google Git
Sign in
apache/flink/master/./flink-python/docs
tree: ba1d1d6b9081a00e232a410605d5c9a986838aa1 [path history] [tgz]
  1. _static/
  2. _templates/
  3. assets/
  4. cookbook/
  5. developer_guide/
  6. examples/
  7. getting_started/
  8. locales/
  9. reference/
  10. user_guide/
  11. conf.py
  12. index.rst
  13. Makefile
  14. pyproject.toml
  15. README.md
  16. uv.lock
flink-python/docs/README.md

PyFlink Documentation

This directory contains the Sphinx-based Python documentation for Apache Flink (PyDocs). It includes API reference documentation (auto-generated from docstrings) and a user guide with tutorials and guides for PyFlink users.

The built documentation is published at:

  • English: https://nightlies.apache.org/flink/flink-docs-{version}/api/python/
  • Chinese: https://nightlies.apache.org/flink/flink-docs-{version}/api/python/zh/

Prerequisites

The docs directory has its own pyproject.toml with all Sphinx dependencies. You can install them with either uv (recommended) or pip.

Using uv (recommended)

cd flink-python/docs
uv sync

That's it. The Makefile auto-detects uv and will use uv run to invoke Sphinx.

Using pip

cd flink-python/docs
pip install -r <(uv pip compile pyproject.toml)

Or install the packages listed in docs/pyproject.toml manually into your environment.

Building the Documentation

All commands should be run from the flink-python/docs/ directory.

English only

make html

Output: _build/html/ — open _build/html/index.html in a browser.

English + Chinese

make html-zh

This builds English into _build/html/ and Chinese into _build/html/zh/. A language toggle in the navbar allows switching between them.

Chinese only

If the English docs are already built (e.g., in CI where lint-python.sh builds them first):

make zh

This runs gettext → sphinx-intl update → Chinese HTML build into _build/html/zh/.

Serving locally

make serve

Then open http://localhost:8080/.

Directory Structure

flink-python/docs/
├── conf.py                  # Sphinx configuration
├── index.rst                # Root toctree
├── Makefile                 # Build targets
├── _static/                 # Custom CSS/JS
├── _templates/              # Custom Jinja2 templates (e.g., language switcher)
├── reference/               # Auto-generated API reference (from docstrings)
├── examples/                # Code examples
├── user_guide/              # Guides and tutorials
│   ├── index.rst
│   ├── table/               # Table API guides
│   ├── datastream/          # DataStream API guides
│   └── *.rst                # General guides (config, debugging, etc.)
└── locales/                 # Translation files (see below)
    └── zh/
        └── LC_MESSAGES/
            └── user_guide/
                └── *.po     # Chinese translations

Cross-References to Main Flink Docs

Links to pages in the main Flink documentation (the Hugo site) use the :flinkdoc: role, powered by Sphinx's extlinks extension:

See the :flinkdoc:`CLI documentation <docs/deployment/cli/>` for details.

This renders as a link to https://nightlies.apache.org/flink/flink-docs-master/docs/deployment/cli/ by default.

The base URL is controlled by the FLINK_DOCS_BASE_URL environment variable:

# For a specific release:
export FLINK_DOCS_BASE_URL="https://nightlies.apache.org/flink/flink-docs-release-2.2"
make html

In CI, this is set automatically from the git branch name (see .github/workflows/docs.sh). For local builds, it defaults to flink-docs-master.

Translations (Chinese)

Chinese translations use Sphinx‘s built-in internationalization system based on GNU gettext. Here’s how it works:

How it works

  1. .pot files (PO Templates) — Auto-generated from the English .rst sources. Each paragraph becomes a translatable string (msgid). These are build artifacts in _build/gettext/ and should never be edited manually.

  2. .po files (Portable Object) — One per .rst file per language, stored in locales/zh/LC_MESSAGES/. Each file contains msgid/msgstr pairs where msgid is the English source text and msgstr is the Chinese translation. These are the files you edit.

  3. .mo files (Machine Object) — Compiled binary versions of .po files, generated automatically during the build. These are gitignored.

Updating an existing translation

Edit the relevant .po file in locales/zh/LC_MESSAGES/user_guide/. For example, to update the Chinese translation of the debugging guide:

# Edit the .po file
vi locales/zh/LC_MESSAGES/user_guide/debugging.po

Each entry looks like:

#: ../../user_guide/debugging.rst:10
msgid "Logging"
msgstr "日志"
  • msgid — The English source text (do not modify)
  • msgstr — The Chinese translation (this is what you edit)
  • Empty msgstr "" means untranslated (the English text will be shown)

After editing, rebuild the Chinese docs:

make zh

Adding translations for a new page

When a new .rst page is added to user_guide/, the translation workflow is:

# 1. Regenerate .pot templates from the updated English sources
make gettext

# 2. Create/update .po files for Chinese
sphinx-intl update -p _build/gettext -l zh

# 3. Edit the new .po file in locales/zh/LC_MESSAGES/user_guide/
#    Fill in msgstr values with Chinese translations

# 4. Build to verify
make html-zh

Syncing after English content changes

When the English .rst source is updated, the .po files need to be synced:

make gettext
sphinx-intl update -p _build/gettext -l zh

This preserves existing translations and marks changed entries as #, fuzzy. Fuzzy entries use the old translation as a suggestion but need review. Remove the #, fuzzy marker after verifying the translation is still correct.

RST markup in translations

Translations must preserve RST inline markup exactly. Common patterns:

# Inline code
msgid "Use ``TableEnvironment`` to create tables."
msgstr "使用 ``TableEnvironment`` 创建表。"

# Bold
msgid "This is **important**."
msgstr "这是 **重要的**。"

# Links
msgid "See `Apache Flink <https://flink.apache.org>`_ for details."
msgstr "详情请参阅 `Apache Flink <https://flink.apache.org>`_ 。"

Note: RST requires a space before and after inline markup ( , `**`, etc.). This includes before Chinese punctuation — code 。not code。``.

Adding a New User Guide Page

  1. Create the .rst file in the appropriate subdirectory:

    vi user_guide/my_new_page.rst

    Use an existing page as a template for the license header and heading style.

  2. Add the page to the parent index.rst toctree:

    .. toctree::
    :maxdepth: 2

    existing_page
    my_new_page        <-- add here

  3. Generate the translation stub:

    make gettext
sphinx-intl update -p _build/gettext -l zh

  4. Optionally populate locales/zh/LC_MESSAGES/user_guide/my_new_page.po with Chinese translations.

  5. Build and verify:

    make html-zh