This is an automated email from the ASF dual-hosted git repository. sijie pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-pulsar.git
The following commit(s) were added to refs/heads/master by this push: new d8c171b [website] fix javadoc template (#2245) d8c171b is described below commit d8c171bff58659cbc801db5987508ca860827a88 Author: Sijie Guo <guosi...@gmail.com> AuthorDate: Thu Jul 26 23:47:55 2018 -0700 [website] fix javadoc template (#2245) ### Motivation the existing site is using `{% javadoc ... %}` for templating url to the javadoc link of a given java class. since the new site doesn't use any templating language. we need to fix these templates. ### Changes I am extending the `inject` logic in markdown rendering, providing a similar feature as existing site. when you want to create a link to a java class, you can use `{@inject: javadoc:<class-name>:<relative-class-path-to-javadoc-location>}`. Example: if you want to link to https://pulsar.incubator.apache.org/api/admin/org/apache/pulsar/client/admin/PulsarAdmin.html, you can use `{@inject: javadoc:PulsarAdmin:admin/org/apache/pulsar/client/admin/PulsarAdmin}` and the rendered result will be [PulsarAdmin](https://pulsar.incubator.apache.org/api/admin/org/apache/pulsar/client/admin/PulsarAdmin.html) --- site2/docs/admin-api-brokers.md | 2 +- site2/docs/admin-api-clusters.md | 2 +- site2/docs/admin-api-namespaces.md | 2 +- site2/docs/admin-api-overview.md | 2 +- site2/docs/administration-dashboard.md | 2 +- site2/docs/administration-geo.md | 2 +- site2/docs/client-libraries-java.md | 20 ++++++++++---------- site2/docs/cookbooks-partitioned.md | 2 +- site2/docs/deploy-kubernetes.md | 2 +- site2/docs/functions-api.md | 4 ++-- site2/docs/functions-metrics.md | 2 +- .../getting-started-concepts-and-architecture.md | 4 ++-- site2/website/scripts/replace.js | 12 ++---------- site2/website/siteConfig.js | 17 ++++++++++++++++- 14 files changed, 41 insertions(+), 34 deletions(-) diff --git a/site2/docs/admin-api-brokers.md b/site2/docs/admin-api-brokers.md index 9cc3023..3d7ea5c 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 9f0d23e..eb873ef 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 9ebd770..a203c83 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 2220418..db77a8d 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 9305f1e..0c4bf9d 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 1093323..4f65127 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 1913bea..ff52a25 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.clien [...] +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/ [...] Here's an example: diff --git a/site2/docs/cookbooks-partitioned.md b/site2/docs/cookbooks-partitioned.md index 82c8885..58bd8d7 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 39dc06a..9627165 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 b261837..247b8f3 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 c445bd3..896a401 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 ec99f27..af62864 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 b6bcaf9..57d8129 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 30ca549..0f316b1 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: '',