This is an automated email from the ASF dual-hosted git repository.
tison pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 78800444d97 Document how to generate apidoc python (#283)
78800444d97 is described below
commit 78800444d972f9415851b8ce4569317308cda0e6
Author: tison <[email protected]>
AuthorDate: Mon Nov 14 10:14:13 2022 +0800
Document how to generate apidoc python (#283)
Signed-off-by: tison <[email protected]>
---
site2/tools/{api => apidoc}/python/README.md | 22 +++++++++++++++-------
.../python/pdoc-generator-helper.sh} | 9 ++++++---
.../python/pdoc-generator.sh} | 17 ++++++++++-------
.../python/pydoctor-generator-helper.sh} | 18 +++++++++++++-----
.../python/pydoctor-generator.sh} | 17 ++++++++++-------
5 files changed, 54 insertions(+), 29 deletions(-)
diff --git a/site2/tools/api/python/README.md
b/site2/tools/apidoc/python/README.md
similarity index 61%
rename from site2/tools/api/python/README.md
rename to site2/tools/apidoc/python/README.md
index 8a969d114da..f58eba5d7b3 100644
--- a/site2/tools/api/python/README.md
+++ b/site2/tools/apidoc/python/README.md
@@ -21,14 +21,22 @@
# Pulsar Client Generated Docs
-Pulsar's Python docs used to be generated for every wesbite build, but this is
unnecessary. We now generate
-the docs for each version by running the
[build-docs-in-docker.sh](./build-docs-in-docker.sh) script in this
-directory.
+## 3.0.0 and Later
-## Example
+Releases start from 3.0.0 uses
[`pydoctor`](https://github.com/twisted/pydoctor) to generate API docs.
-When starting in the root directory of the project, you can run:
+When starting in the root directory of the `pulsar-site` project, you can run:
```shell
-PULSAR_VERSION=2.8.3 ./site2/tools/python-client/build-docs-in-docker.sh
-```
\ No newline at end of file
+PULSAR_VERSION=3.0.0 ./site2/tools/apidoc/python/pydoctor-generator.sh
+```
+
+## Before 3.0.0
+
+Releases before 3.0.0 uses [`pdoc`](https://github.com/mitmproxy/pdoc) to
generate API docs.
+
+When starting in the root directory of the `pulsar-site` project, you can run:
+
+```shell
+PULSAR_VERSION=2.8.3 ./site2/tools/apidoc/python/pdoc-generator.sh
+```
diff --git a/site2/tools/api/python/generate-python-client-docs.sh
b/site2/tools/apidoc/python/pdoc-generator-helper.sh
similarity index 89%
copy from site2/tools/api/python/generate-python-client-docs.sh
copy to site2/tools/apidoc/python/pdoc-generator-helper.sh
index 1a69e0f4f4c..70cd508c94c 100755
--- a/site2/tools/api/python/generate-python-client-docs.sh
+++ b/site2/tools/apidoc/python/pdoc-generator-helper.sh
@@ -19,12 +19,15 @@
#
-set -e
+set -x -e
-PULSAR_VERSION="${PULSAR_VERSION:-2.9.1}"
+if [ -z "$PULSAR_VERSION" ]; then
+ echo "PULSAR_VERSION must be set."
+ exit 1
+fi
python -m pip install --upgrade pip
-pip install pdoc
+pip install -U pdoc
pip install pulsar-client==${PULSAR_VERSION}
pdoc pulsar -o /pulsar/site2/website-next/static/api/python/${PULSAR_VERSION}
diff --git a/site2/tools/api/python/build-docs-in-docker.sh
b/site2/tools/apidoc/python/pdoc-generator.sh
similarity index 88%
copy from site2/tools/api/python/build-docs-in-docker.sh
copy to site2/tools/apidoc/python/pdoc-generator.sh
index b11cbb0147c..ba924d830a1 100755
--- a/site2/tools/api/python/build-docs-in-docker.sh
+++ b/site2/tools/apidoc/python/pdoc-generator.sh
@@ -19,24 +19,27 @@
#
-set -e
+set -x -e
+
+if [ -z "$PULSAR_VERSION" ]; then
+ echo "PULSAR_VERSION must be set."
+ exit 1
+fi
BUILD_IMAGE_NAME="${BUILD_IMAGE_NAME:-apachepulsar/pulsar-build}"
-# Use python 3.8 for now because it works for 2.7, 2.8, and 2.9.
PYTHON_VERSION="${PYTHON_VERSION:-3.8}"
PYTHON_SPEC="${PYTHON_SPEC:-cp38-cp38}"
-# ROOT_DIR should be an absolute path so that Docker accepts it as a valid
volumes path
+IMAGE=$BUILD_IMAGE_NAME:manylinux-$PYTHON_SPEC
+
+# ROOT_DIR should be an absolute path so that Docker accepts it as a valid
volumes path.
ROOT_DIR=`cd $(dirname $0)/../../../..; pwd`
cd $ROOT_DIR
echo "Build Python docs for python version $PYTHON_VERSION, spec $PYTHON_SPEC,
and pulsar version ${PULSAR_VERSION}"
-
-IMAGE=$BUILD_IMAGE_NAME:manylinux-$PYTHON_SPEC
-
echo "Using image: $IMAGE"
VOLUME_OPTION=${VOLUME_OPTION:-"-v $ROOT_DIR:/pulsar"}
-COMMAND="/pulsar/site2/tools/api/python/generate-python-client-docs.sh"
+COMMAND="/pulsar/site2/tools/apidoc/python/pdoc-generator-helper.sh"
DOCKER_CMD="docker run -e PULSAR_VERSION=${PULSAR_VERSION} --entrypoint
${COMMAND} -i ${VOLUME_OPTION} ${IMAGE}"
$DOCKER_CMD
diff --git a/site2/tools/api/python/generate-python-client-docs.sh
b/site2/tools/apidoc/python/pydoctor-generator-helper.sh
similarity index 58%
rename from site2/tools/api/python/generate-python-client-docs.sh
rename to site2/tools/apidoc/python/pydoctor-generator-helper.sh
index 1a69e0f4f4c..97c4db8c011 100755
--- a/site2/tools/api/python/generate-python-client-docs.sh
+++ b/site2/tools/apidoc/python/pydoctor-generator-helper.sh
@@ -19,12 +19,20 @@
#
-set -e
+set -x -e
-PULSAR_VERSION="${PULSAR_VERSION:-2.9.1}"
+if [ -z "$PULSAR_VERSION" ]; then
+ echo "PULSAR_VERSION must be set."
+ exit 1
+fi
python -m pip install --upgrade pip
-pip install pdoc
-pip install pulsar-client==${PULSAR_VERSION}
-pdoc pulsar -o /pulsar/site2/website-next/static/api/python/${PULSAR_VERSION}
+pip install -U pydoctor
+git clone https://github.com/apache/pulsar-client-python --single-branch
--branch v$PULSAR_VERSION
+pydoctor --make-html \
+
--html-viewsource-base=https://github.com/apache/pulsar-client-python/tree/v$PULSAR_VERSION
\
+ --docformat=numpy --theme=readthedocs \
+ --intersphinx=https://docs.python.org/3/objects.inv \
+
--html-output=/pulsar/site2/website-next/static/api/python/${PULSAR_VERSION} \
+ pulsar-client-python/pulsar
diff --git a/site2/tools/api/python/build-docs-in-docker.sh
b/site2/tools/apidoc/python/pydoctor-generator.sh
similarity index 88%
rename from site2/tools/api/python/build-docs-in-docker.sh
rename to site2/tools/apidoc/python/pydoctor-generator.sh
index b11cbb0147c..4c60c21d0ab 100755
--- a/site2/tools/api/python/build-docs-in-docker.sh
+++ b/site2/tools/apidoc/python/pydoctor-generator.sh
@@ -19,24 +19,27 @@
#
-set -e
+set -x -e
+
+if [ -z "$PULSAR_VERSION" ]; then
+ echo "PULSAR_VERSION must be set."
+ exit 1
+fi
BUILD_IMAGE_NAME="${BUILD_IMAGE_NAME:-apachepulsar/pulsar-build}"
-# Use python 3.8 for now because it works for 2.7, 2.8, and 2.9.
PYTHON_VERSION="${PYTHON_VERSION:-3.8}"
PYTHON_SPEC="${PYTHON_SPEC:-cp38-cp38}"
-# ROOT_DIR should be an absolute path so that Docker accepts it as a valid
volumes path
+IMAGE=$BUILD_IMAGE_NAME:manylinux-$PYTHON_SPEC
+
+# ROOT_DIR should be an absolute path so that Docker accepts it as a valid
volumes path.
ROOT_DIR=`cd $(dirname $0)/../../../..; pwd`
cd $ROOT_DIR
echo "Build Python docs for python version $PYTHON_VERSION, spec $PYTHON_SPEC,
and pulsar version ${PULSAR_VERSION}"
-
-IMAGE=$BUILD_IMAGE_NAME:manylinux-$PYTHON_SPEC
-
echo "Using image: $IMAGE"
VOLUME_OPTION=${VOLUME_OPTION:-"-v $ROOT_DIR:/pulsar"}
-COMMAND="/pulsar/site2/tools/api/python/generate-python-client-docs.sh"
+COMMAND="/pulsar/site2/tools/apidoc/python/pydoctor-generator-helper.sh"
DOCKER_CMD="docker run -e PULSAR_VERSION=${PULSAR_VERSION} --entrypoint
${COMMAND} -i ${VOLUME_OPTION} ${IMAGE}"
$DOCKER_CMD
