This is an automated email from the ASF dual-hosted git repository.
hxb pushed a commit to branch release-1.15
in repository https://gitbox.apache.org/repos/asf/flink.git
commit d6bf30a013569c4a8e0cd546f3105296c7b32efe
Author: huangxingbo <h...@apache.org>
AuthorDate: Wed Nov 16 10:57:11 2022 +0800
[FLINK-29966][python][doc] Replace and Redesign PyFlink API doc
This closes #21328.
---
flink-python/dev/lint-python.sh | 2 +-
flink-python/docs/_templates/autosummary/base.rst | 22 ++++++++
flink-python/docs/_templates/autosummary/class.rst | 35 +++++++++++++
flink-python/docs/conf.py | 14 +++++-
flink-python/docs/pyflink.common.rst | 28 -----------
flink-python/docs/pyflink.datastream.rst | 46 -----------------
flink-python/docs/pyflink.metrics.rst | 28 -----------
flink-python/docs/pyflink.rst | 35 -------------
flink-python/docs/pyflink.table.rst | 58 ----------------------
9 files changed, 70 insertions(+), 198 deletions(-)
diff --git a/flink-python/dev/lint-python.sh b/flink-python/dev/lint-python.sh
index 871b07cc1fc..62519e09882 100755
--- a/flink-python/dev/lint-python.sh
+++ b/flink-python/dev/lint-python.sh
@@ -322,7 +322,7 @@ function install_sphinx() {
fi
fi
- $CURRENT_DIR/install_command.sh -q Sphinx==2.4.4 Docutils==0.17.1
"Jinja2<3.1.0" 2>&1 >/dev/null
+ $CURRENT_DIR/install_command.sh -q Sphinx==4.5.0 importlib-metadata==4.4.0
Docutils==0.17.1 pydata_sphinx_theme==0.11.0 sphinx_mdinclude==0.5.3
"Jinja2<3.1.0" 2>&1 >/dev/null
if [ $? -ne 0 ]; then
echo "pip install sphinx failed \
please try to exec the script again.\
diff --git a/flink-python/docs/_templates/autosummary/base.rst
b/flink-python/docs/_templates/autosummary/base.rst
new file mode 100644
index 00000000000..5b5918d11ba
--- /dev/null
+++ b/flink-python/docs/_templates/autosummary/base.rst
@@ -0,0 +1,22 @@
+.. 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.
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ fullname }}
diff --git a/flink-python/docs/_templates/autosummary/class.rst
b/flink-python/docs/_templates/autosummary/class.rst
new file mode 100644
index 00000000000..87a4aab80ca
--- /dev/null
+++ b/flink-python/docs/_templates/autosummary/class.rst
@@ -0,0 +1,35 @@
+.. 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.
+
+{% extends "!autosummary/class.rst" %}
+
+{% if '__init__' in methods %}
+{% set caught_result = methods.remove('__init__') %}
+{% endif %}
+
+{% block methods %}
+{% if methods %}
+
+ .. rubric:: Methods
+
+ .. autosummary::
+ {% for item in methods %}
+ ~{{ name }}.{{ item }}
+ {%- endfor %}
+
+{% endif %}
+{% endblock %}
diff --git a/flink-python/docs/conf.py b/flink-python/docs/conf.py
index e32182ea514..42db33665d6 100644
--- a/flink-python/docs/conf.py
+++ b/flink-python/docs/conf.py
@@ -63,6 +63,8 @@ extensions = [
'sphinx.ext.mathjax',
'sphinx.ext.inheritance_diagram',
'sphinx.ext.doctest',
+ 'sphinx.ext.autosummary',
+ 'sphinx_mdinclude'
]
# Add any paths that contain templates here, relative to this directory.
@@ -89,10 +91,15 @@ language = None
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# Look at the first line of the docstring for function and method signatures.
+autosummary_generate = True
autodoc_docstring_signature = True
# -- Options for HTML output -------------------------------------------------
@@ -100,13 +107,16 @@ autodoc_docstring_signature = True
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
-html_theme = 'nature'
+html_theme = 'pydata_sphinx_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
-# html_theme_options = {}
+html_theme_options = {
+ "collapse_navigation": True,
+ "navigation_depth": 0
+}
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
diff --git a/flink-python/docs/pyflink.common.rst
b/flink-python/docs/pyflink.common.rst
deleted file mode 100644
index d011887a9d1..00000000000
--- a/flink-python/docs/pyflink.common.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-..
################################################################################
- 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.
-
################################################################################
-
-pyflink.common package
-======================
-
-Module contents
----------------
-
-.. automodule:: pyflink.common
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/flink-python/docs/pyflink.datastream.rst
b/flink-python/docs/pyflink.datastream.rst
deleted file mode 100644
index ee5126e630e..00000000000
--- a/flink-python/docs/pyflink.datastream.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-..
################################################################################
- 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.
-
################################################################################
-
-pyflink.datastream package
-==========================
-
-Module contents
----------------
-
-.. automodule:: pyflink.datastream
- :members:
- :undoc-members:
- :show-inheritance:
-
-pyflink.datastream.state module
-------------------------------------
-.. automodule:: pyflink.datastream.state
- :members:
- :undoc-members:
-
-pyflink.datastream.connectors module
-------------------------------------
-.. automodule:: pyflink.datastream.connectors
- :members:
- :undoc-members:
-
-pyflink.datastream.window module
---------------------------------
-.. automodule:: pyflink.datastream.window
- :members:
- :undoc-members:
diff --git a/flink-python/docs/pyflink.metrics.rst
b/flink-python/docs/pyflink.metrics.rst
deleted file mode 100644
index 90f43010004..00000000000
--- a/flink-python/docs/pyflink.metrics.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-..
################################################################################
- 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.
-
################################################################################
-
-pyflink.metrics package
-=======================
-
-Module contents
----------------
-
-.. automodule:: pyflink.metrics
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/flink-python/docs/pyflink.rst b/flink-python/docs/pyflink.rst
deleted file mode 100644
index 81ba9f70bcd..00000000000
--- a/flink-python/docs/pyflink.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-..
################################################################################
- 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.
-
################################################################################
-
-pyflink package
-===============
-
-Subpackages
------------
-
-.. toctree::
- :maxdepth: 1
-
- pyflink.common
- pyflink.table
- pyflink.datastream
-
-.. automodule:: pyflink
- :members:
- :undoc-members:
- :show-inheritance:
diff --git a/flink-python/docs/pyflink.table.rst
b/flink-python/docs/pyflink.table.rst
deleted file mode 100644
index 4302b2cf288..00000000000
--- a/flink-python/docs/pyflink.table.rst
+++ /dev/null
@@ -1,58 +0,0 @@
-..
################################################################################
- 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.
-
################################################################################
-
-pyflink.table package
-=====================
-
-Module contents
----------------
-
-.. automodule:: pyflink.table
- :members:
- :undoc-members:
- :show-inheritance:
-
-pyflink.table.expressions module
---------------------------------
-.. automodule:: pyflink.table.expressions
- :members:
- :undoc-members:
-
-pyflink.table.window module
----------------------------
-.. automodule:: pyflink.table.window
- :members:
- :undoc-members:
-
-pyflink.table.descriptors module
--------------------------------------
-.. automodule:: pyflink.table.descriptors
- :members:
- :undoc-members:
-
-pyflink.table.catalog module
-----------------------------
-.. automodule:: pyflink.table.catalog
- :members:
- :undoc-members:
-
-pyflink.table.module module
--------------------------------------
-.. automodule:: pyflink.table.module
- :members:
- :undoc-members:
