[#4829] improvement(client-python): Sphinx Initialization (#4830)

### What changes were proposed in this pull request?

* Add Sphinx configuration files and templates for generating documents
automatically
* Add new task `doc` for Sphinx documents generation and remove old task
for docs
* Generated website files will be in `docs/build/html`, open
`docs/build/html/index.html` to see the home page
* Feel free to improve this document configuration (what contents should
be included, add project logos in documents, etc.)

#### Current Document Display
<img width="1470" alt="image"
src="https://github.com/user-attachments/assets/e98b0233-b9e6-4c68-91a1-487b6ead1c07">

> NOTES:
> * The current theme is [Furo](https://pradyunsg.me/furo/), feel free
to change if other theme is better
> * It still needs a lot of revision, like mentioned in
#4797 (comment)

### Why are the changes needed?

Fix: #4829

### Does this PR introduce _any_ user-facing change?

No

### How was this patch tested?

./gradlew client:client-python:doc

---------

Co-authored-by: TimWang <[email protected]>

build.gradle.kts

@@ -508,7 +508,9 @@ tasks.rat {
     "clients/client-python/apache_gravitino.egg-info/*",
     "clients/client-python/gravitino/utils/http_client.py",
     "clients/client-python/tests/unittests/htmlcov/*",
-    "clients/client-python/tests/integration/htmlcov/*"
+    "clients/client-python/tests/integration/htmlcov/*",
+    "clients/client-python/docs/build",
+    "clients/client-python/docs/source/generated"
   )
 
   // Add .gitignore excludes to the Apache Rat exclusion list.

clients/client-python/.gitignore

@@ -28,7 +28,6 @@ dist
 build
 README.md
 gravitino/version.ini
-docs
 
 # Unit test / coverage reports
 htmlcov/
@@ -44,3 +43,7 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
+
+# Documentation Related
+docs/build
+docs/source/generated

clients/client-python/build.gradle.kts

@@ -272,9 +272,10 @@ tasks {
     }
   }
 
-  val pydoc by registering(VenvTask::class) {
-    venvExec = "python"
-    args = listOf("scripts/generate_doc.py")
+  val doc by registering(VenvTask::class) {
+    workingDir = projectDir.resolve("./docs")
+    venvExec = "make"
+    args = listOf("html")
   }
 
   val distribution by registering(VenvTask::class) {
@@ -318,7 +319,8 @@ tasks {
   val clean by registering(Delete::class) {
     delete("build")
     delete("dist")
-    delete("docs")
+    delete("docs/build")
+    delete("docs/source/generated")
     delete("gravitino/version.ini")
     delete("apache_gravitino.egg-info")
     delete("tests/unittests/htmlcov")

clients/client-python/docs/Makefile

@@ -0,0 +1,37 @@
+# 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.
+
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

clients/client-python/docs/make.bat

@@ -0,0 +1,52 @@
+@REM Licensed to the Apache Software Foundation (ASF) under one
+@REM or more contributor license agreements.  See the NOTICE file
+@REM distributed with this work for additional information
+@REM regarding copyright ownership.  The ASF licenses this file
+@REM to you under the Apache License, Version 2.0 (the
+@REM "License"); you may not use this file except in compliance
+@REM with the License.  You may obtain a copy of the License at
+
+@REM   http://www.apache.org/licenses/LICENSE-2.0
+
+@REM Unless required by applicable law or agreed to in writing,
+@REM software distributed under the License is distributed on an
+@REM "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+@REM KIND, either express or implied.  See the License for the
+@REM specific language governing permissions and limitations
+@REM under the License.
+
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

clients/client-python/docs/source/_templates/custom-class-template.rst

@@ -0,0 +1,49 @@
+.. 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 }}
+
+.. autoclass:: {{ objname }}
+   :members:                                    
+   :show-inheritance:                           
+   :inherited-members:                          
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

clients/client-python/docs/source/_templates/custom-module-template.rst

@@ -0,0 +1,83 @@
+.. 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}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+      :toctree:                                          
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:                                          
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:                                          
+      :template: custom-class-template.rst               
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:                                          
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst                 
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

clients/client-python/docs/source/conf.py

@@ -0,0 +1,76 @@
+"""
+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.
+"""
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import sys
+import re
+
+sys.path.insert(0, os.path.abspath('../..'))
+
+from gravitino.constants.version import SETUP_FILE
+from gravitino.exceptions.base import GravitinoRuntimeException
+
+VERSION_PATTERN = r"version\s*=\s*['\"]([^'\"]+)['\"]"
+AUTHOR_PATTERN = r"author\s*=\s*['\"]([^'\"]+)['\"]"
+
+
+with open(SETUP_FILE, "r", encoding="utf-8") as f:
+    setup_content = f.read()
+
+    version_group = re.search(VERSION_PATTERN, setup_content)
+    if version_group is not None:
+        project_version = version_group.group(1)
+    else:
+        raise GravitinoRuntimeException("Can't find valid author info in setup.py")
+
+    author_group = re.search(AUTHOR_PATTERN, setup_content)
+    if author_group is not None:
+        project_author = author_group.group(1)
+    else:
+        raise GravitinoRuntimeException("Can't find valid author info in setup.py")
+
+project = 'Apache Gravitino Python Client'
+copyright = '2024, Apache Software Foundation'
+author = project_author
+release = project_version
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']

clients/client-python/docs/source/index.rst

@@ -0,0 +1,33 @@
+.. 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.
+
+.. Apache Gravitino Python Client documentation master file, created by
+   sphinx-quickstart on Fri Aug 30 14:16:27 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Apache Gravitino Python Client documentation
+============================================
+
+Packages
+-----------
+.. autosummary::
+    :toctree: generated
+    :template: custom-module-template.rst
+    :recursive:
+
+    gravitino

clients/client-python/requirements-dev.txt

@@ -30,3 +30,5 @@ readerwriterlock==1.0.9
 docker==7.1.0
 pyjwt[crypto]==2.8.0
 jwcrypto==1.5.6
+sphinx==7.1.2
+furo==2024.8.6