sijie closed pull request #2245: [website] fix javadoc template
URL: https://github.com/apache/incubator-pulsar/pull/2245
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/site2/docs/admin-api-brokers.md b/site2/docs/admin-api-brokers.md
index 9cc3023898..3d7ea5cbd8 100644
--- a/site2/docs/admin-api-brokers.md
+++ b/site2/docs/admin-api-brokers.md
@@ -13,7 +13,7 @@ Pulsar brokers consist of two components:
* The [`brokers`](reference-pulsar-admin.md#brokers) command of the
[`pulsar-admin`](reference-pulsar-admin.md) tool
* The `/admin/v2/brokers` endpoint of the admin [REST
API](reference-rest-api.md)
-* The `brokers` method of the {% javadoc PulsarAdmin admin
org.apache.pulsar.client.admin.PulsarAdmin %} object in the [Java
API](client-libraries-java.md)
+* The `brokers` method of the {@inject:
javadoc:PulsarAdmin:/admin/org/apache/pulsar/client/admin/PulsarAdmin.html}
object in the [Java API](client-libraries-java.md)
In addition to being configurable when you start them up, brokers can also be
[dynamically configured](#dynamic-broker-configuration).
diff --git a/site2/docs/admin-api-clusters.md b/site2/docs/admin-api-clusters.md
index 9f0d23eab9..eb873efd38 100644
--- a/site2/docs/admin-api-clusters.md
+++ b/site2/docs/admin-api-clusters.md
@@ -11,7 +11,7 @@ Clusters can be managed via:
* The [`clusters`](reference-pulsar-admin.md#clusters) command of the
[`pulsar-admin`](reference-pulsar-admin.md) tool
* The `/admin/v2/clusters` endpoint of the admin [REST
API](reference-rest-api.md)
-* The `clusters` method of the {% javadoc PulsarAdmin admin
org.apache.pulsar.client.admin.PulsarAdmin %} object in the [Java
API](client-libraries-java.md)
+* The `clusters` method of the {@inject:
javadoc:PulsarAdmin:/admin/org/apache/pulsar/client/admin/PulsarAdmin} object
in the [Java API](client-libraries-java.md)
## Clusters resources
diff --git a/site2/docs/admin-api-namespaces.md
b/site2/docs/admin-api-namespaces.md
index 9ebd77029a..a203c83317 100644
--- a/site2/docs/admin-api-namespaces.md
+++ b/site2/docs/admin-api-namespaces.md
@@ -10,7 +10,7 @@ Namespaces can be managed via:
* The [`namespaces`](reference-pulsar-admin.md#clusters) command of the
[`pulsar-admin`](reference-pulsar-admin.md) tool
* The `/admin/v2/namespaces` endpoint of the admin [REST
API](reference-rest-api.md)
-* The `namespaces` method of the {% javadoc PulsarAdmin admin
org.apache.pulsar.client.admin.PulsarAdmin %} object in the [Java
API](client-libraries-java.md)
+* The `namespaces` method of the {@inject:
javadoc:PulsarAdmin:/admin/org/apache/pulsar/client/admin/PulsarAdmin} object
in the [Java API](client-libraries-java.md)
## Namespaces resources
diff --git a/site2/docs/admin-api-overview.md b/site2/docs/admin-api-overview.md
index 2220418825..db77a8db3f 100644
--- a/site2/docs/admin-api-overview.md
+++ b/site2/docs/admin-api-overview.md
@@ -50,7 +50,7 @@ You can find documentation for the REST API exposed by Pulsar
[brokers](referenc
### Java admin client
-To use the Java admin API, instantiate a {% javadoc PulsarAdmin admin
org.apache.pulsar.client.admin.PulsarAdmin %} object, specifying a URL for a
Pulsar [broker](reference-terminology.md#broker) and a {% javadoc
ClientConfiguration admin org.apache.pulsar.client.admin.ClientConfiguration
%}. Here's a minimal example using `localhost`:
+To use the Java admin API, instantiate a {@inject:
javadoc:PulsarAdmin:/admin/org/apache/pulsar/client/admin/PulsarAdmin} object,
specifying a URL for a Pulsar [broker](reference-terminology.md#broker) and a
{@inject:
javadoc:ClientConfiguration:/admin/org/apache/pulsar/client/admin/ClientConfiguration}.
Here's a minimal example using `localhost`:
```java
URL url = new URL("http://localhost:8080";);
diff --git a/site2/docs/administration-dashboard.md
b/site2/docs/administration-dashboard.md
index 9305f1e2d6..0c4bf9d2fd 100644
--- a/site2/docs/administration-dashboard.md
+++ b/site2/docs/administration-dashboard.md
@@ -12,7 +12,7 @@ A [Django](https://www.djangoproject.com) web app is used to
render the collecte
## Install
-The easiest way to use the dashboard is to run it inside a
[Docker](https://www.docker.com/products/docker) container. A
[`Dockerfile`](pulsar:repo_url/dashboard/Dockerfile) to generate the image is
provided.
+The easiest way to use the dashboard is to run it inside a
[Docker](https://www.docker.com/products/docker) container. A {@inject:
github:`Dockerfile`:/dashboard/Dockerfile} to generate the image is provided.
To generate the Docker image:
diff --git a/site2/docs/administration-geo.md b/site2/docs/administration-geo.md
index 1093323bf8..4f65127a61 100644
--- a/site2/docs/administration-geo.md
+++ b/site2/docs/administration-geo.md
@@ -87,7 +87,7 @@ Once you've created a global namespace, any topics that
producers or consumers c
By default, messages are replicated to all clusters configured for the
namespace. You can restrict replication selectively by specifying a replication
list for a message. That message will then be replicated only to the subset in
the replication list.
-Below is an example for the [Java API](client-libraries-java.md). Note the use
of the `setReplicationClusters` method when constructing the {% javadoc Message
client org.apache.pulsar.client.api.Message %} object:
+Below is an example for the [Java API](client-libraries-java.md). Note the use
of the `setReplicationClusters` method when constructing the {@inject:
javadoc:Message:/client/org/apache/pulsar/client/api/Message} object:
```java
List<String> restrictReplicationTo = Arrays.asList(
diff --git a/site2/docs/client-libraries-java.md
b/site2/docs/client-libraries-java.md
index 1913bea142..ff52a25acb 100644
--- a/site2/docs/client-libraries-java.md
+++ b/site2/docs/client-libraries-java.md
@@ -71,7 +71,7 @@ pulsar+ssl://pulsar.us-west.example.com:6651
## Client configuration
-You can instantiate a {% javadoc PulsarClient client
org.apache.pulsar.client.api.PulsarClient %} object using just a URL for the
target Pulsar [cluster](reference-terminology.md#cluster), like this:
+You can instantiate a {@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object
using just a URL for the target Pulsar
[cluster](reference-terminology.md#cluster), like this:
```java
PulsarClient client = PulsarClient.builder()
@@ -82,14 +82,14 @@ PulsarClient client = PulsarClient.builder()
> #### Default broker URLs for standalone clusters
> If you're running a cluster in [standalone
> mode](getting-started-standalone.md), the broker will be available at the
> `pulsar://localhost:6650` URL by default.
-Check out the Javadoc for the {% javadoc PulsarClient client
org.apache.pulsar.client.api.PulsarClient %} class for a full listing of
configurable parameters.
+Check out the Javadoc for the {@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} class
for a full listing of configurable parameters.
> In addition to client-level configuration, you can also apply
> [producer](#configuring-producers) and [consumer](#configuring-consumers)
> specific configuration, as you'll see in the sections below.
## Producers
-In Pulsar, producers write messages to topics. Once you've instantiated a {%
javadoc PulsarClient client org.apache.pulsar.client.api.PulsarClient %} object
(as in the section [above](#client-configuration)), you can create a {% javadoc
Producer client org.apache.pulsar.client.api.Producer %} for a specific Pulsar
[topic](reference-terminology.md#topic).
+In Pulsar, producers write messages to topics. Once you've instantiated a
{@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object
(as in the section [above](#client-configuration)), you can create a {@inject:
javadoc:Producer:/client/org/apache/pulsar/client/api/Producer} for a specific
Pulsar [topic](reference-terminology.md#topic).
```java
Producer<byte[]> producer = client.newProducer()
@@ -129,7 +129,7 @@ stringProducer.send("My message");
### Configuring producers
-If you instantiate a `Producer` object specifying only a topic name, as in the
example above, the producer will use the default configuration. To use a
non-default configuration, there's a variety of configurable parameters that
you can set. For a full listing, see the Javadoc for the {% javadoc
ProducerBuilder client org.apache.pulsar.client.api.ProducerBuilder %} class.
Here's an example:
+If you instantiate a `Producer` object specifying only a topic name, as in the
example above, the producer will use the default configuration. To use a
non-default configuration, there's a variety of configurable parameters that
you can set. For a full listing, see the Javadoc for the {@inject
javadoc:ProducerBuilder:/client/org/apache/pulsar/client/api/ProducerBuilder}
class. Here's an example:
```java
Producer<byte[]> producer = client.newProducer()
@@ -156,7 +156,7 @@
producer.sendAsync("my-async-message".getBytes()).thenAccept(msgId -> {
});
```
-As you can see from the example above, async send operations return a {%
javadoc MessageId client org.apache.pulsar.client.api.MessageId %} wrapped in a
[`CompletableFuture`](http://www.baeldung.com/java-completablefuture).
+As you can see from the example above, async send operations return a {@inject
javadoc:MessageId:/client/org/apache/pulsar/client/api/MessageId} wrapped in a
[`CompletableFuture`](http://www.baeldung.com/java-completablefuture).
### Configuring messages
@@ -176,9 +176,9 @@ get a future returned.
## Consumers
-In Pulsar, consumers subscribe to topics and handle messages that producers
publish to those topics. You can instantiate a new
[consumer](reference-terminology.md#consumer) by first instantiating a {%
javadoc PulsarClient client org.apache.pulsar.client.api.PulsarClient %} object
and passing it a URL for a Pulsar broker (as [above](#client-configuration)).
+In Pulsar, consumers subscribe to topics and handle messages that producers
publish to those topics. You can instantiate a new
[consumer](reference-terminology.md#consumer) by first instantiating a
{@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object
and passing it a URL for a Pulsar broker (as [above](#client-configuration)).
-Once you've instantiated a {% javadoc PulsarClient client
org.apache.pulsar.client.api.PulsarClient %} object, you can create a {%
javadoc Consumer client org.apache.pulsar.client.api.Consumer %} by specifying
a [topic](reference-terminology.md#topic) and a
[subscription](getting-started-concepts-and-architecture.md#subscription-modes).
+Once you've instantiated a {@inject:
javadoc:PulsarClient:/client/org/apache/pulsar/client/api/PulsarClient} object,
you can create a {@inject:
javadoc:Consumer:/client/org/apache/pulsar/client/api/Consumer} by specifying a
[topic](reference-terminology.md#topic) and a
[subscription](getting-started-concepts-and-architecture.md#subscription-modes).
```java
Consumer consumer = client.newConsumer()
@@ -203,7 +203,7 @@ do {
### Configuring consumers
-If you instantiate a `Consumer` object specifying only a topic and
subscription name, as in the example above, the consumer will use the default
configuration. To use a non-default configuration, there's a variety of
configurable parameters that you can set. For a full listing, see the Javadoc
for the {% javadoc ConsumerBuilder client
org.apache.pulsar.client.api.ConsumerBuilder %} class. Here's an example:
+If you instantiate a `Consumer` object specifying only a topic and
subscription name, as in the example above, the consumer will use the default
configuration. To use a non-default configuration, there's a variety of
configurable parameters that you can set. For a full listing, see the Javadoc
for the {@inject:
javadoc:ConsumerBuilder:/client/org/apache/pulsar/client/api/ConsumerBuilder}
class. Here's an example:
Here's an example configuration:
@@ -226,7 +226,7 @@ Here's an example:
CompletableFuture<Message> asyncMessage = consumer.receiveAsync();
```
-Async receive operations return a {% javadoc Message client
org.apache.pulsar.client.api.Message %} wrapped inside of a
[`CompletableFuture`](http://www.baeldung.com/java-completablefuture).
+Async receive operations return a {@inject
javadoc:Message:/client/org/apache/pulsar/client/api/Message} wrapped inside of
a [`CompletableFuture`](http://www.baeldung.com/java-completablefuture).
### Multi-topic subscriptions
@@ -302,7 +302,7 @@ consumerBuilder
## Reader interface {#readers}
-With the [reader
interface](getting-started-concepts-and-architecture.md#reader-interface),
Pulsar clients can "manually position" themselves within a topic, reading all
messages from a specified message onward. The Pulsar API for Java enables you
to create {% javadoc Reader client org.apache.pulsar.client.api.Reader %}
objects by specifying a topic, a {% javadoc MessageId client
org.apache.pulsar.client.api.MessageId %}, and {% javadoc ReaderConfiguration
client org.apache.pulsar.client.api.ReaderConfiguration %}.
+With the [reader
interface](getting-started-concepts-and-architecture.md#reader-interface),
Pulsar clients can "manually position" themselves within a topic, reading all
messages from a specified message onward. The Pulsar API for Java enables you
to create {@inject:
javadoc:Reader:/client/org/apache/pulsar/client/api/Reader} objects by
specifying a topic, a {@inject:
javadoc:MessageId:/client/org/apache/pulsar/client/api/MessageId}, and {@inject
javadoc:ReaderConfiguration:/client/org/apache/pulsar/client/api/ReaderConfiguration}.
Here's an example:
diff --git a/site2/docs/cookbooks-partitioned.md
b/site2/docs/cookbooks-partitioned.md
index 82c8885687..58bd8d74d3 100644
--- a/site2/docs/cookbooks-partitioned.md
+++ b/site2/docs/cookbooks-partitioned.md
@@ -39,7 +39,7 @@ producer.send("Partitioned topic message".getBytes());
#### Custom message router
-To use a custom message router, you need to provide an implementation of the
{% javadoc MessageRouter client org.apache.pulsar.client.api.MessageRouter %}
interface, which has just one `choosePartition` method:
+To use a custom message router, you need to provide an implementation of the
{@inject:
javadoc:MessageRouter:/client/org/apache/pulsar/client/api/MessageRouter}
interface, which has just one `choosePartition` method:
```java
public interface MessageRouter extends Serializable {
diff --git a/site2/docs/deploy-kubernetes.md b/site2/docs/deploy-kubernetes.md
index 39dc06aa76..9627165d3b 100644
--- a/site2/docs/deploy-kubernetes.md
+++ b/site2/docs/deploy-kubernetes.md
@@ -6,7 +6,7 @@ sidebar_label: Kubernetes
Pulsar can be easily deployed in [Kubernetes](https://kubernetes.io/)
clusters, either in managed clusters on [Google Kubernetes
Engine](#pulsar-on-google-kubernetes-engine) or [Amazon Web
Services](https://aws.amazon.com/) or in [custom
clusters](#pulsar-on-a-custom-kubernetes-cluster).
-The deployment method shown in this guide relies on [YAML](http://yaml.org/)
definitions for Kubernetes [resources](https://kubernetes.io/docs/reference/).
The [`kubernetes`](pulsar:repo_url/kubernetes) subdirectory of the [Pulsar
package](pulsar:download_page_url) holds resource definitions for:
+The deployment method shown in this guide relies on [YAML](http://yaml.org/)
definitions for Kubernetes [resources](https://kubernetes.io/docs/reference/).
The {@inject: github:`kubernetes`:/kubernetes} subdirectory of the [Pulsar
package](pulsar:download_page_url) holds resource definitions for:
* A two-bookie BookKeeper cluster
* A three-node ZooKeeper cluster
diff --git a/site2/docs/functions-api.md b/site2/docs/functions-api.md
index b26183797d..247b8f3ce8 100644
--- a/site2/docs/functions-api.md
+++ b/site2/docs/functions-api.md
@@ -144,7 +144,7 @@ class WordFilter(Function):
Writing Pulsar Functions in Java involves implementing one of two interfaces:
* The
[`java.util.Function`](https://docs.oracle.com/javase/8/docs/api/java/util/function/Function.html)
interface
-* The {% javadoc Function client org.apache.pulsar.functions.api.Function %}
interface. This interface works much like the `java.util.Function` interface,
but with the important difference that it provides a {% javadoc Context client
org.apache.pulsar.functions.api.Context %} object that you can use in a
[variety of ways](#context)
+* The {@inject:
javadoc:Function:client/org/apache/pulsar/functions/api/Function} interface.
This interface works much like the `java.util.Function` interface, but with the
important difference that it provides a {@inject:
javadoc:Context:/client/org/apache/pulsar/functions/api/Context} object that
you can use in a [variety of ways](#context)
### Getting started
@@ -237,7 +237,7 @@ Function name | Description
### Java context object
-The {% javadoc Context client org.apache.pulsar.functions.api.Context %}
interface provides a number of methods that you can use to access the
function's [context](#context). The various method signatures for the `Context`
interface are listed below:
+The {@inject: javadoc:Context:/client/org/apache/pulsar/functions/api/Context}
interface provides a number of methods that you can use to access the
function's [context](#context). The various method signatures for the `Context`
interface are listed below:
```java
public interface Context {
diff --git a/site2/docs/functions-metrics.md b/site2/docs/functions-metrics.md
index c445bd3970..896a401ad3 100644
--- a/site2/docs/functions-metrics.md
+++ b/site2/docs/functions-metrics.md
@@ -15,7 +15,7 @@ For a guide to accessing metrics created by Pulsar Functions,
see the guide to [
## Java SDK
-If you're creating a Pulsar Function using the [Java
SDK](functions-api.md#java-sdk), the {% javadoc Context client
org.apache.pulsar.functions.api.Context %} object has a `recordMetric` method
that you can use to register both a name for the metric and a value. Here's the
signature for that method:
+If you're creating a Pulsar Function using the [Java
SDK](functions-api.md#java-sdk), the {@inject:
javadoc:Context:/client/org/apache/pulsar/functions/api/Context} object has a
`recordMetric` method that you can use to register both a name for the metric
and a value. Here's the signature for that method:
```java
void recordMetric(String metricName, double value);
diff --git a/site2/docs/getting-started-concepts-and-architecture.md
b/site2/docs/getting-started-concepts-and-architecture.md
index ec99f27c32..af62864eb8 100644
--- a/site2/docs/getting-started-concepts-and-architecture.md
+++ b/site2/docs/getting-started-concepts-and-architecture.md
@@ -86,7 +86,7 @@ Messages can be acknowledged either one by one or
cumulatively. With cumulative
#### Listeners
-Client libraries can provide their own listener implementations for consumers.
The [Java client](client-libraries-java.md), for example, provides a {% javadoc
MesssageListener client org.apache.pulsar.client.api.MessageListener %}
interface. In this interface, the `received` method is called whenever a new
message is received.
+Client libraries can provide their own listener implementations for consumers.
The [Java client](client-libraries-java.md), for example, provides a {@inject:
javadoc:MesssageListener:/client/org/apache/pulsar/client/api/MessageListener}
interface. In this interface, the `received` method is called whenever a new
message is received.
### Topics
@@ -220,7 +220,7 @@ Key hash | If a key property has been specified on the
message, the partitioned
Single default partition | If no key is provided, each producer's message will
be routed to a dedicated partition, initially random selected | Per-producer
ordering
Round robin distribution | If no key is provided, all messages will be routed
to different partitions in round-robin fashion to achieve maximum throughput. |
None
-In addition to these default modes, you can also create a custom routing mode
if you're using the [Java client](client-libraries-java.md) by implementing the
{% javadoc MessageRouter client org.apache.pulsar.client.api.MessageRouter %}
interface.
+In addition to these default modes, you can also create a custom routing mode
if you're using the [Java client](client-libraries-java.md) by implementing the
{@inject:
javadoc:MessageRouter:/client/org/apache/pulsar/client/api/MessageRouter}
interface.
diff --git a/site2/website/scripts/replace.js b/site2/website/scripts/replace.js
index b6bcaf99c9..57d8129786 100644
--- a/site2/website/scripts/replace.js
+++ b/site2/website/scripts/replace.js
@@ -21,15 +21,10 @@ function downloadPageUrl() {
return `${siteConfig.baseUrl}download`
}
-function pulsarRepoUrl() {
- return siteConfig.githubUrl;
-}
-
function binaryReleaseUrl(version) {
return
`http://www.apache.org/dyn/closer.cgi/incubator/pulsar/pulsar-${version}/apache-pulsar-${version}-bin.tar.gz`
}
-
function doReplace(options) {
replace(options)
.then(changes => {
@@ -52,7 +47,6 @@ const from = [
/{{pulsar:version}}/g,
/pulsar:binary_release_url/g,
/pulsar:download_page_url/g,
- /pulsar:repo_url/g
];
@@ -66,8 +60,7 @@ const options = {
to: [
`${latestVersion}-incubating`,
binaryReleaseUrl(`${latestVersion}-incubating`),
- downloadPageUrl(),
- pulsarRepoUrl()
+ downloadPageUrl()
],
dry: false
};
@@ -89,8 +82,7 @@ for (v of versions) {
to: [
`${v}-incubating`,
binaryReleaseUrl(`${v}-incubating`),
- downloadPageUrl(),
- pulsarRepoUrl()
+ downloadPageUrl()
],
dry: true
};
diff --git a/site2/website/siteConfig.js b/site2/website/siteConfig.js
index 30ca549552..0f316b1aa2 100644
--- a/site2/website/siteConfig.js
+++ b/site2/website/siteConfig.js
@@ -13,6 +13,14 @@ const createVariableInjectionPlugin = variables => {
// the passed Remarkable instance.
// -> the Markdown markup in the variable will be converted to HTML.
inject: (key) => {
+ keyparts = key.split(":");
+ // javadoc:<name>:<url_path>
+ if (keyparts[0] == 'javadoc') {
+ return renderUrl(initializedPlugin, javadocUrl, keyparts);
+ // githubUrl:<name>:<path>
+ } else if (keyparts[0] == 'github') {
+ return renderUrl(initializedPlugin, githubUrl + "/tree/master/",
keyparts);
+ }
return initializedPlugin.render(variables[key])
}
});
@@ -29,15 +37,22 @@ const createVariableInjectionPlugin = variables => {
};
};
+const renderUrl = (initializedPlugin, baseUrl, keyparts) => {
+ content = '[' + keyparts[1] + '](' + baseUrl + keyparts[2] + ')';
+ rendered_content = initializedPlugin.render(content);
+ rendered_content = rendered_content.replace('<p>', '');
+ rendered_content = rendered_content.replace('</p>', '');
+ return rendered_content;
+};
const url = 'https://pulsar.incubator.apache.org';
+const javadocUrl = url + '/api';
const githubUrl = 'https://github.com/apache/incubator-pulsar';
const baseUrl = '/staging/';
const siteVariables = {
};
-
const siteConfig = {
title: 'Apache Pulsar' /* title for your website */,
tagline: '',
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
