This is an automated email from the ASF dual-hosted git repository.
mmerli pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-client-cpp.git
The following commit(s) were added to refs/heads/main by this push:
new efd2a1e Fix doxygen generation (#103)
efd2a1e is described below
commit efd2a1e9127761693501045f75609dee1d07b9e5
Author: Yunze Xu <[email protected]>
AuthorDate: Fri Nov 4 04:55:16 2022 +0800
Fix doxygen generation (#103)
* Fix doxygen generation
* Fix outdated MainPage
* Fix outdated protobuf docs
---
.gitignore | 1 +
Doxyfile | 6 +-
README.md | 8 ++-
docs/MainPage.md | 180 -------------------------------------------------------
4 files changed, 9 insertions(+), 186 deletions(-)
diff --git a/.gitignore b/.gitignore
index 4fd7cf1..ee4f28f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -72,6 +72,7 @@ compile_commands.json
# doxygen files
apidocs/
+doxygen/
# generated files
generated/
diff --git a/Doxyfile b/Doxyfile
index b3ac004..145948c 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -77,7 +77,7 @@ PROJECT_LOGO =
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.
-OUTPUT_DIRECTORY = ../target/doxygen
+OUTPUT_DIRECTORY = ./doxygen
# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
# directories (in 2 levels) under the output directory of each output format
and
@@ -809,7 +809,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = include docs/MainPage.md
+INPUT = include ./README.md
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1001,7 +1001,7 @@ FILTER_SOURCE_PATTERNS =
# (index.html). This can be useful if you have a project on for instance GitHub
# and want to reuse the introduction page also for the doxygen output.
-USE_MDFILE_AS_MAINPAGE = docs/MainPage.md
+USE_MDFILE_AS_MAINPAGE = ./README.md
#---------------------------------------------------------------------------
# Configuration options related to source browsing
diff --git a/README.md b/README.md
index 9b0c2bf..33df78a 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,11 @@
# Pulsar C++ client library
-Examples for using the API to publish and consume messages can be found under
the [examples](examples) folder.
+Examples for using the API to publish and consume messages can be found under
the [examples](https://github.com/apache/pulsar-client-cpp/tree/main/examples)
folder.
+
+## Generate the API documents
+
+Pulsar C++ client uses [doxygen](https://www.doxygen.nl) to build API
documents. After installing `doxygen`, you only need to run `doxygen` to
generate the API documents whose main page is under the
`doxygen/html/index.html` path.
## Requirements
@@ -32,8 +36,6 @@ Examples for using the API to publish and consume messages
can be found under th
* [libcurl](https://curl.se/libcurl/)
* [openssl](https://github.com/openssl/openssl)
-It's recommended to use Protocol Buffer 2.6 because it's verified by CI, but
3.x also works.
-
The default supported [compression types](include/pulsar/CompressionType.h)
are:
* `CompressionNone`
diff --git a/docs/MainPage.md b/docs/MainPage.md
deleted file mode 100644
index 2115b9a..0000000
--- a/docs/MainPage.md
+++ /dev/null
@@ -1,180 +0,0 @@
-<!--
-
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
--->
-
-# The Pulsar C++ client
-
-Welcome to the Doxygen documentation for [Pulsar](https://pulsar.apache.org/).
-
-## Supported platforms
-
-The Pulsar C++ client has been successfully tested on **MacOS** and **Linux**.
-
-## System requirements
-
-You need to have the following installed to use the C++ client:
-
-* [CMake](https://cmake.org/)
-* [Boost](http://www.boost.org/)
-* [Protocol Buffers](https://developers.google.com/protocol-buffers/) 2.6
-* [Log4CXX](https://logging.apache.org/log4cxx)
-* [libcurl](https://curl.haxx.se/libcurl/)
-* [Google Test](https://github.com/google/googletest)
-
-## Compilation
-
-There are separate compilation instructions for [MacOS](#macos) and
[Linux](#linux). For both systems, start by cloning the Pulsar repository:
-
-```shell
-$ git clone https://github.com/apache/pulsar
-```
-
-### Linux
-
-First, install all of the necessary dependencies:
-
-```shell
-$ apt-get install cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \
- libprotobuf-dev libboost-all-dev libgtest-dev libjsoncpp-dev
-```
-
-Then compile and install [Google Test](https://github.com/google/googletest):
-
-```shell
-$ git clone https://github.com/google/googletest.git && cd googletest
-$ sudo cmake .
-$ sudo make
-$ sudo cp *.a /usr/lib
-```
-
-Finally, compile the Pulsar client library for C++ inside the Pulsar repo:
-
-```shell
-$ cd pulsar-client-cpp
-$ cmake .
-$ make
-```
-
-The resulting files, `libpulsar.so` and `libpulsar.a`, will be placed in the
`lib` folder of the repo while two tools, `perfProducer` and `perfConsumer`,
will be placed in the `perf` directory.
-
-### MacOS
-
-First, install all of the necessary dependencies:
-
-```shell
-# OpenSSL installation
-$ brew install openssl
-$ export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/
-$ export OPENSSL_ROOT_DIR=/usr/local/opt/openssl/
-
-# Protocol Buffers installation
-$ brew tap homebrew/versions
-$ brew install protobuf260
-$ brew install boost
-$ brew install log4cxx
-
-# Google Test installation
-$ git clone https://github.com/google/googletest.git
-$ cd googletest
-$ git checkout release-1.12.1
-$ cmake .
-$ make install
-```
-
-Then compile the Pulsar client library in the repo that you cloned:
-
-```shell
-$ cd pulsar-client-cpp
-$ cmake .
-$ make
-```
-
-## Consumer
-
-```cpp
-Client client("pulsar://localhost:6650");
-
-Consumer consumer;
-Result result = client.subscribe("persistent://public/default/my-topic",
"my-subscribtion-name", consumer);
-if (result != ResultOk) {
- LOG_ERROR("Failed to subscribe: " << result);
- return -1;
-}
-
-Message msg;
-
-while (true) {
- consumer.receive(msg);
- LOG_INFO("Received: " << msg << " with payload '" <<
msg.getDataAsString() << "'");
-
- consumer.acknowledge(msg);
-}
-
-client.close();
-```
-
-
-## Producer
-
-```cpp
-Client client("pulsar://localhost:6650");
-
-Producer producer;
-Result result = client.createProducer("persistent://public/default/my-topic",
producer);
-if (result != ResultOk) {
- LOG_ERROR("Error creating producer: " << result);
- return -1;
-}
-
-// Publish 10 messages to the topic
-for(int i=0;i<10;i++){
- Message msg = MessageBuilder().setContent("my-message").build();
- Result res = producer.send(msg);
- LOG_INFO("Message sent: " << res);
-}
-client.close();
-```
-
-## Authentication
-
-```cpp
-ClientConfiguration config = ClientConfiguration();
-config.setUseTls(true);
-std::string certfile = "/path/to/cacert.pem";
-
-ParamMap params;
-params["tlsCertFile"] = "/path/to/client-cert.pem";
-params["tlsKeyFile"] = "/path/to/client-key.pem";
-config.setTlsTrustCertsFilePath(certfile);
-config.setTlsAllowInsecureConnection(false);
-AuthenticationPtr auth = pulsar::AuthFactory::create("/path/to/libauthtls.so",
params);
-config.setAuth(auth);
-
-Client client("pulsar+ssl://my-broker.com:6651",config);
-```
-
-## Code formatting
-After you changed code, run auto-formatting by the following command.
-
-```bash
-make format
-```
-You need to have the following installed to use the auto-formatting.
-* [clang-format 5.0](https://clang.llvm.org/)
