Include the C extension when generating API docs (#126)

### Motivation

#85 (comment)

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.

Author: BewareMyPower

README.md

@@ -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!

RELEASE.md

@@ -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 [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 \
   --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 .

pulsar/__init__.py

@@ -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
@@ -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
@@ -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)