Skip to content

Include the C extension when generating API docs #126

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 26, 2023
Merged

Include the C extension when generating API docs #126

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,18 +109,22 @@ python3 ./tests/pulsar_test.py 'PulsarTest.test_tls_auth'

## 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!
Expand Down
5 changes: 4 additions & 1 deletion RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,12 +225,15 @@ git checkout vX.Y.0
# 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 .
Expand Down
11 changes: 5 additions & 6 deletions pulsar/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -575,8 +575,8 @@ def create_producer(self, topic,

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
Expand Down Expand Up @@ -751,7 +751,7 @@ def my_listener(consumer, message):
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
Expand Down Expand Up @@ -1304,14 +1304,13 @@ def acknowledge(self, message):

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)
Expand Down