This is an automated email from the ASF dual-hosted git repository.
xyz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-client-python.git
The following commit(s) were added to refs/heads/main by this push:
new 1a2fb07 [docs] Fix the incorrect API docs generation steps in the
release process (#131)
1a2fb07 is described below
commit 1a2fb076ea2a00afce27a076bad5a8a655bd3bd3
Author: Yunze Xu <[email protected]>
AuthorDate: Mon Jun 12 10:08:12 2023 +0800
[docs] Fix the incorrect API docs generation steps in the release process
(#131)
### Motivation
https://github.com/apache/pulsar-client-python/pull/126 adds the
instruction to include the `_pulsar` C module when generating the API
docs. However, it does not work when the library is installed from
`pip`. It only works when the wheel is installed from `dist/*.whl` that
is generated by the `python3 setup.py bdist_wheel` command in the
README.
The reason is the official Python wheel uses `auditwheel` to package all
dynamic libraries, so the `_pulsar.so` depends on another dynamic
library in the relative path. e.g.
```bash
$ ldd
~/.local/lib/python3.8/site-packages/_pulsar.cpython-38-x86_64-linux-gnu.so
libpulsar-b6dad138.so =>
/home/xyz/.local/lib/python3.8/site-packages/pulsar_client.libs/libpulsar-b6dad138.so
(0x00007f8dc09b3000)
...
```
If we copy the `_pulsar.cpython-38-x86_64-linux-gnu.so` into the project
directory, the `libpulsar-b6dad138.so` will not be found.
### Modifications
In `RELEASE.md`, specify the path of `_pulsar.so` directly.
---
RELEASE.md | 28 ++++++++++++++++++----------
1 file changed, 18 insertions(+), 10 deletions(-)
diff --git a/RELEASE.md b/RELEASE.md
index f323414..e9f9ea9 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -219,29 +219,37 @@ Then, create a PR in
[`pulsar-site`](https://github.com/apache/pulsar-site) repo
For minor releases, skip this section. For major releases, you should generate
the HTML files into the [`pulsar-site`](https://github.com/apache/pulsar-site)
repo:
```bash
+# Use the first two version numbers, e.g. export VERSION=3.2
+VERSION=X.Y
+
+# You need to install the wheel to have the _pulsar.so installed
+# It's better to run the following commands in an empty directory
+python3 -m pip install pulsar-client==$VERSION.0 --force-reinstall
+C_MODULE_PATH=$(python3 -c 'import _pulsar, os; print(_pulsar.__file__)')
+
git clone [email protected]:apache/pulsar-client-python.git
cd pulsar-client-python
-git checkout vX.Y.0
-# It's better to replace this URL with the URL of your own fork
+git checkout v$VERSION.0
+# You can skip this step if you already have the `pulsar-site` repository in
your local env.
+# In this case, you only need to modify the `--html-output` parameter in the
following command.
git clone [email protected]:apache/pulsar-site.git
sudo python3 -m pip install pydoctor
-cp $(python3 -c 'import _pulsar, os; print(_pulsar.__file__)') ./_pulsar.so
pydoctor --make-html \
-
--html-viewsource-base=https://github.com/apache/pulsar-client-python/tree/vX.Y.0
\
+
--html-viewsource-base=https://github.com/apache/pulsar-client-python/tree/v$VERSION.0
\
--docformat=numpy --theme=readthedocs \
--intersphinx=https://docs.python.org/3/objects.inv \
- --html-output=./pulsar-site/site2/website-next/static/api/python/X.Y.x \
+ --html-output=./pulsar-site/static/api/python/$VERSION.x \
--introspect-c-modules \
- ./_pulsar.so \
+ $C_MODULE_PATH \
pulsar
cd pulsar-site
-git checkout -b py-docs-X.Y
+git checkout -b py-docs-$VERSION
git add .
-git commit -m "Generate Python client X.Y.0 doc"
-git push origin py-docs-X.Y
+git commit -m "Generate Python client $VERSION.0 doc"
+git push origin py-docs-$VERSION
```
-Then open a PR like: https://github.com/apache/pulsar-site/pull/342
+Then open a PR like: https://github.com/apache/pulsar-site/pull/600
## Announce the release
