Include the C extension when generating API docs (#126)
### Motivation
https://github.com/apache/pulsar-client-python/issues/85#issuecomment-1531069608
Some targets in the API docs are referenced from the `_pulsar` module,
while the `pydoctor` command does not generate API docs for it. It's not
friendly to users, e.g. they cannot find which values could
`_pulsar.ConsumerType` be.
```
pulsar/__init__.py:695: Cannot find link target for "_pulsar.ConsumerType"
```
### Modifications
Fix the documents to describe how to include the API docs for the
`_pulsar` module when generating API docs. It also fixes some other
warnings when running the `pydoctor` command.
diff --git a/README.md b/README.md
index 5ebbdd2..8b3a908 100644
--- a/README.md
+++ b/README.md
@@ -109,18 +109,22 @@
## Generate API docs
-Pulsar Python Client uses [pydoctor](https://github.com/twisted/pydoctor) to generate API docs. To generate by yourself, run the following command in the root path of this repository:
+Pulsar Python Client uses [pydoctor](https://github.com/twisted/pydoctor) to generate API docs. To generate by yourself, you need to install the Python library first. Then run the following command in the root path of this repository:
```bash
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/<release-version-tag> \
--docformat=numpy --theme=readthedocs \
--intersphinx=https://docs.python.org/3/objects.inv \
--html-output=<path-to-apidocs> \
+ --introspect-c-modules \
+ ./_pulsar.so \
pulsar
```
+Then the index page will be generated in `<path-to-apidocs>/index.html`.
+
## Contribute
We welcome contributions from the open source community!
diff --git a/RELEASE.md b/RELEASE.md
index a056edb..f323414 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -225,12 +225,15 @@
# It's better to replace this URL with the URL of your own fork
git clone git@github.com: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 \
--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 \
- pulsar-client-python/pulsar
+ --introspect-c-modules \
+ ./_pulsar.so \
+ pulsar
cd pulsar-site
git checkout -b py-docs-X.Y
git add .
diff --git a/pulsar/__init__.py b/pulsar/__init__.py
index 843274b..dbf3d82 100644
--- a/pulsar/__init__.py
+++ b/pulsar/__init__.py
@@ -575,8 +575,8 @@
Supported modes:
- * `PartitionsRoutingMode.RoundRobinDistribution`
- * `PartitionsRoutingMode.UseSinglePartition`.
+ * ``PartitionsRoutingMode.RoundRobinDistribution``
+ * ``PartitionsRoutingMode.UseSinglePartition``
lazy_start_partitioned_producers: bool, default=False
This config affects producers of partitioned topics only. It controls whether producers register
and connect immediately to the owner broker of each partition or start lazily on demand. The internal
@@ -751,7 +751,7 @@
Periods of seconds for consumer to auto discover match topics.
initial_position: InitialPosition, default=InitialPosition.Latest
Set the initial position of a consumer when subscribing to the topic.
- It could be either: `InitialPosition.Earliest` or `InitialPosition.Latest`.
+ It could be either: ``InitialPosition.Earliest`` or ``InitialPosition.Latest``.
crypto_key_reader: CryptoKeyReader, optional
Symmetric encryption class implementation, configuring public key encryption messages for the producer
and private key decryption messages for the consumer
@@ -1304,14 +1304,13 @@
Parameters
----------
-
- message:
+ message : Message, _pulsar.Message, _pulsar.MessageId
The received message or message id.
Raises
------
OperationNotSupported
- if `message` is not allowed to acknowledge
+ if ``message`` is not allowed to acknowledge
"""
if isinstance(message, Message):
self._consumer.acknowledge(message._message)
