This is an automated email from the ASF dual-hosted git repository.
jshao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new f8e39b4f5 [#4829] improvement(client-python): Sphinx Initialization
(#4830)
f8e39b4f5 is described below
commit f8e39b4f512539e8d60651c1f6b6f2206ab245a2
Author: noidname01 <[email protected]>
AuthorDate: Tue Sep 10 00:32:29 2024 +0800
[#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
https://github.com/apache/gravitino/issues/4797#issuecomment-2323197095
### 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 | 4 +-
clients/client-python/.gitignore | 5 +-
clients/client-python/build.gradle.kts | 10 +--
.../client-python/{.gitignore => docs/Makefile} | 51 ++++++-------
clients/client-python/docs/make.bat | 52 ++++++++++++++
.../source/_templates/custom-class-template.rst | 49 +++++++++++++
.../source/_templates/custom-module-template.rst | 83 ++++++++++++++++++++++
clients/client-python/docs/source/conf.py | 76 ++++++++++++++++++++
clients/client-python/docs/source/index.rst | 33 +++++++++
clients/client-python/requirements-dev.txt | 2 +
clients/client-python/scripts/generate_doc.py | 42 -----------
11 files changed, 329 insertions(+), 78 deletions(-)
diff --git a/build.gradle.kts b/build.gradle.kts
index 93feb52de..da13580a3 100644
--- a/build.gradle.kts
+++ b/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.
diff --git a/clients/client-python/.gitignore b/clients/client-python/.gitignore
index 20c0f8c5a..18200b504 100644
--- a/clients/client-python/.gitignore
+++ b/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
\ No newline at end of file
diff --git a/clients/client-python/build.gradle.kts
b/clients/client-python/build.gradle.kts
index 625e28c14..bebf536f6 100644
--- a/clients/client-python/build.gradle.kts
+++ b/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")
diff --git a/clients/client-python/.gitignore
b/clients/client-python/docs/Makefile
similarity index 51%
copy from clients/client-python/.gitignore
copy to clients/client-python/docs/Makefile
index 20c0f8c5a..5c5e2b940 100644
--- a/clients/client-python/.gitignore
+++ b/clients/client-python/docs/Makefile
@@ -5,9 +5,9 @@
# 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
-#
+
+# 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
@@ -15,32 +15,23 @@
# 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)
-**/.pytest_cache/**
-**/__pycache__/**
-apache_gravitino.egg-info
-vevn
-venv
-.vevn
-.venv
-.idea
-dist
-build
-README.md
-gravitino/version.ini
-docs
+.PHONY: help Makefile
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
+# 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)
diff --git a/clients/client-python/docs/make.bat
b/clients/client-python/docs/make.bat
new file mode 100644
index 000000000..240af4fc7
--- /dev/null
+++ b/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
diff --git
a/clients/client-python/docs/source/_templates/custom-class-template.rst
b/clients/client-python/docs/source/_templates/custom-class-template.rst
new file mode 100644
index 000000000..8fbff577e
--- /dev/null
+++ b/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 %}
\ No newline at end of file
diff --git
a/clients/client-python/docs/source/_templates/custom-module-template.rst
b/clients/client-python/docs/source/_templates/custom-module-template.rst
new file mode 100644
index 000000000..fd8901bc4
--- /dev/null
+++ b/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 %}
\ No newline at end of file
diff --git a/clients/client-python/docs/source/conf.py
b/clients/client-python/docs/source/conf.py
new file mode 100644
index 000000000..3d9233cb4
--- /dev/null
+++ b/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']
diff --git a/clients/client-python/docs/source/index.rst
b/clients/client-python/docs/source/index.rst
new file mode 100644
index 000000000..c78aa3bf4
--- /dev/null
+++ b/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
diff --git a/clients/client-python/requirements-dev.txt
b/clients/client-python/requirements-dev.txt
index 002e08964..a26827832 100644
--- a/clients/client-python/requirements-dev.txt
+++ b/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
diff --git a/clients/client-python/scripts/generate_doc.py
b/clients/client-python/scripts/generate_doc.py
deleted file mode 100644
index 5bad95409..000000000
--- a/clients/client-python/scripts/generate_doc.py
+++ /dev/null
@@ -1,42 +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.
-"""
-
-import pydoc
-import os
-import shutil
-
-from gravitino.constants.doc import DOC_DIR
-from gravitino.constants.root import GRAVITINO_DIR, MODULE_NAME
-
-if __name__ == "__main__":
-
- if os.path.exists(DOC_DIR):
- # If doc folder exists, delete it
- shutil.rmtree(DOC_DIR)
-
- # Create a new doc folder
- os.makedirs(DOC_DIR)
- # Change work directory to doc folder
- os.chdir(DOC_DIR)
-
- # Write doc for top module
- pydoc.writedoc(MODULE_NAME)
-
- # Write doc for submodules
- pydoc.writedocs(GRAVITINO_DIR.as_posix(), MODULE_NAME + ".")
