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/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new c1b8442 [Doc] Update the site2/README.md file (#4130)
c1b8442 is described below
commit c1b84428374fcf4b0eedc3305437a85635c8e12b
Author: Jennifer Huang <[email protected]>
AuthorDate: Fri Apr 26 11:22:49 2019 +0800
[Doc] Update the site2/README.md file (#4130)
### Motivation
We've applied GSoD project for Pulsar docs, and more contributors might
read this file, I some typos when reading the document.
### Modifications
1. Delete the redundant link and information on versioning for Line 169.
2. Refine some sentences to be a little more smooth.
3. Improve notes in the `Running the site locally` section.
---
site2/README.md | 98 ++++++++++++++++++++++++++++-----------------------------
1 file changed, 48 insertions(+), 50 deletions(-)
diff --git a/site2/README.md b/site2/README.md
index 19bb4b9..6783fcf 100644
--- a/site2/README.md
+++ b/site2/README.md
@@ -1,14 +1,12 @@
-
-
# The Pulsar website and documentation
-This `README` is basically the meta-documentation for the Pulsar website and
documentation. Here you'll find instructions on running the site locally
+This `README` is basically the meta-documentation for the Pulsar website and
documentation. You will find instructions on running the site locally.
## Tools
Framework [Docusaurus](https://docusaurus.io/).
-Ensure you have the latest version of [Node](https://nodejs.org/en/download/)
installed. We also recommend you install
[Yarn](https://yarnpkg.com/en/docs/install) as well.
+Ensure you have installed the latest version of
[Node](https://nodejs.org/en/download/). You can install
[Yarn](https://yarnpkg.com/en/docs/install) as well.
> You have to be on Node >= 8.x and Yarn >= 1.5.
@@ -22,23 +20,26 @@ cd website
yarn install
yarn start
```
-
-Note that the `/docs/en/` path shows the documentation for the latest stable
release of Pulsar. Change it to `/docs/en/next/` to show your local changes,
with live refresh.
+> Notes
+>
+> 1. If you have installed `yarn`, you can skip the `yarn install` command.
+> 2. After you enter the `yarn start` command, you will be navigated to a
local address, for example, `http://localhost:3000`. Click `Docs` to see
documentation for the latest release of Pulsar.
+> 3. The `http://localhost:3000/en/versions` path shows the documentation for
all versions. To view your local changes, click `Documentation` in **Latest
Version**, or enter `http://localhost:3000/docs/en/next/standalone` in a
browser.
## Contribute
-The website is comprised of two parts, one is documentation, while the other
is website pages (including blog posts).
+The website is comprised of two parts: one is documentation, the other is
website pages (including blog posts).
-Documentation related pages are placed under `docs` directory. They are
written in [Markdown](http://daringfireball.net/projects/markdown/syntax).
-All documentation pages are versioned. See more details in
[versioning](#versioning) section.
+Documentation related pages are placed in the `docs` directory. They are
written in [Markdown](http://daringfireball.net/projects/markdown/syntax).
+All documentation pages are versioned. For more details, refer to
[versioning](#versioning).
-Website pages are non-versioned. They are placed under `website` directory.
+Website pages are non-versioned. They are placed in the `website` directory.
### Documentation
#### Layout
-All the markdown files are placed under `docs` directory. It is a flat
structure.
+All the markdown files are placed in the `docs` directory. It is a flat
structure.
```
├── docs
@@ -67,7 +68,7 @@ All the files are named in the following convention:
<category>-<page-name>.md
```
-`<category>` is the category within the sidebard that this file belongs to,
while `<page-name>` is the string to name the file within this category.
+`<category>` is the category within the sidebar that this file belongs to,
while `<page-name>` is the string to name the file within this category.
There isn't any constraints on how files are named. It is just a naming
convention for better maintenance.
@@ -75,16 +76,16 @@ There isn't any constraints on how files are named. It is
just a naming conventi
##### Markdown Headers
-All the documents are the usual Markdown files. However you need to add some
Docusaurus-specific fields in Markdown headers in order to link them
+All the documents are usual Markdown files. However you need to add some
Docusaurus-specific fields in Markdown headers in order to link them
correctly to the [Sidebar](#sidebar) and [Navigation Bar](#navigation).
-`id`: A unique document id. If this field is not present, the document's id
will default to its file name (without the extension).
+`id`: A unique document ID. If this field is not specified, the document ID
defaults to its file name (without the extension).
-`title`: The title of your document. If this field is not present, the
document's title will default to its id.
+`title`: The title of the document. If this field is not specified, the
document title defaults to its id.
`hide_title`: Whether to hide the title at the top of the doc.
-`sidebar_label`: The text shown in the document sidebar for this document. If
this field is not present, the document's `sidebar_label` will default to its
title.
+`sidebar_label`: The text shown in the document sidebar for this document. If
this field is not specified, the document `sidebar_label` defaults to its title.
For example:
@@ -98,7 +99,7 @@ sidebar_label: Overview
##### Linking to another document
-You can use relative URLs to other documentation files which will
automatically get converted to the corresponding HTML links when they get
rendered.
+To link to other documentation files, you can use relative URLs, which will be
automatically converted to the corresponding HTML links when they are rendered.
Example:
@@ -106,29 +107,29 @@ Example:
[This links to another document](other-document.md)
```
-This markdown will automatically get converted into a link to
/docs/other-document.html (or the appropriately translated/versioned link) once
it gets rendered.
+The markdown file will be automatically converted into a link to
/docs/other-document.html (or the appropriately translated/versioned link) once
it is rendered.
-This can help when you want to navigate through docs on GitHub since the links
there will be functional links to other documents (still on GitHub),
-but the documents will have the correct HTML links when they get rendered.
+This helps when you want to navigate through docs on GitHub since the links
there are functional links to other documents (still on GitHub),
+and the documents have the correct HTML links when they are rendered.
#### Linking to javadoc of pulsar class
-We have a [remarkable plugin](https://github.com/jonschlinkert/remarkable) for
generating links to the javadoc for pulsar classes.
-You can write them in following syntax:
+We have a [remarkable plugin](https://github.com/jonschlinkert/remarkable) to
generate links to the javadoc for Pulsar classes.
+You can write them in the following syntax:
```shell
{@inject: javadoc:<Display Name>:<Relative-Path-To-Javadoc-Html-File>}
```
-For example, following line generates a hyperlink to the javadoc of
`PulsarAdmin` class.
+For example, the following line generates a hyperlink to the javadoc of
`PulsarAdmin` class.
```shell
{@inject:
javadoc:PulsarAdmin:/admin/org/apache/pulsar/client/admin/PulsarAdmin.html}
```
-#### Linking to files in Pulsar github repo
+#### Linking to files in Pulsar GitHub repository
-We are using same remarkable plugin to generate links to the files in Pulsar
github repo.
+We use the same [remarkable
plugin](https://github.com/jonschlinkert/remarkable) to generate links to files
in Pulsar GitHub repository.
You can write it using similar syntax:
@@ -136,20 +137,20 @@ You can write it using similar syntax:
{@inject: github:<Display Text>:<Relative-Path-To-Files>}
```
-For example, following line generates a hyperlink to the dashboard Dockerfile.
+For example, the following line generates a hyperlink to the dashboard
Dockerfile.
```
{@inject: github:`Dockerfile`:/dashboard/Dockerfile}
```
-For more details about markdown features, you can read
[here](https://docusaurus.io/docs/en/doc-markdown).
+For more details about markdown features, read
[here](https://docusaurus.io/docs/en/doc-markdown).
#### Sidebar
-All the sidebars are defined in a `sidebars.json` file under `website`
directory. The documentation sidebar is named `docs` in that json structure.
+All the sidebars are defined in a `sidebars.json` file in the `website`
directory. The documentation sidebar is named `docs` in the JSON structure.
-When you want to add a page to sidebar, you can add the document `id` you used
in the document header to existing sidebar/category. In the blow example,
-`docs` is the name of the sidebar, "Getting started" is a category within the
sidebar and "pulsar-2.0" is the `id` of one of the documents.
+When you want to add a page to sidebar, you can add the document `id` you used
in the document header to the existing sidebar/category. In the example below,
+`docs` is the name of the sidebar, "Getting started" is a category within the
sidebar, and "pulsar-2.0" is the `id` of a document.
```bash
{
@@ -166,14 +167,11 @@ When you want to add a page to sidebar, you can add the
document `id` you used i
}
```
-For more details about versioning, you can read
[here](https://docusaurus.io/docs/en/navigation).
-
#### Navigation
To add links to the top navigation bar, you can add entries to the
`headerLinks` of `siteConfig.js` under `website` directory.
-See [Navigation and Sidebars](https://docusaurus.io/docs/en/navigation) in
Docusaurus website to learn different types of links
-you can add to the top navigation bar.
+To learn different types of links you can add to the top navigation bar, refer
to [Navigation and Sidebars](https://docusaurus.io/docs/en/navigation).
## Versioning
@@ -183,34 +181,34 @@ Documentation versioning with Docusaurus becomes simpler.
When done with a new r
yarn run version ${version}
```
-This will preserve all markdown files currently in `docs` directory and make
them available as documentation for version `${version}`.
+This preserves all markdown files in the `docs` directory and make them
available as documentation for version `${version}`.
Versioned documents are placed into
`website/versioned_docs/version-${version}`, where `${version}` is the version
number
you supplied in the command above.
Versioned sidebars are also copied into `website/versioned_sidebars` and are
named as `version-${version}-sidebars.json`.
-If you wish to change the documentation for a past version, you can access the
files for that respective version.
+If you want to change the documentation for a previous version, you can access
files for that respective version.
-For more details about versioning, you can read
[here](https://docusaurus.io/docs/en/versioning).
+For more details about versioning, refer to
[Versioning](https://docusaurus.io/docs/en/versioning).
## Translation and Localization
-Docusaurus allows for easy translation functionality using
[Crowdin](https://crowdin.com/).
+Docusaurus makes it easy to use translation functionality using
[Crowdin](https://crowdin.com/).
All the markdown files are written in English. These markdown files are
uploaded to Crowdin
-for translation by the users within a community. Top-level pages are also
written in English.
+for translation by users within a community. Top-level pages are also written
in English.
The strings that are needed to be translated are wrapped in a `<translate>`
tag.
-[Pulsar Website Build](https://builds.apache.org/job/pulsar-website-build/)
will automatically
-pulling down and uploading translations for all the pulsar website
documentation files. Once
-it pulls down those translations from Crowdin, it will build those
translations into the website.
+[Pulsar Website Build](https://builds.apache.org/job/pulsar-website-build/)
+pulls down and uploads translation for all the Pulsar website documentation
files automatically. Once
+it pulls down translation from Crowdin, it will build the translation into the
website.
-### Contribute Translations
+### Contribute Translation
-All the translations are stored and managed in this [Pulsar Crowdin
project](https://crowdin.com/project/apache-pulsar).
-If you would like to contribute translations, you can simply create a Crowdin
account, join the project and make contributions.
-Crowdin provides very good documentation for translators. You can read [those
documentations](https://support.crowdin.com/crowdin-intro/)
-to start contributing.
+Translation is stored and managed in the [Pulsar Crowdin
project](https://crowdin.com/project/apache-pulsar).
+To contribute translation, you can simply create a Crowdin account, join the
project and make contributions.
+Crowdin provides very good documentation for translators. You can read
[Crowdin Knowledge Base](https://support.crowdin.com/crowdin-intro/)
+before contributing.
-Your contributed translations will be licensed under [Apache License
V2](https://www.apache.org/licenses/LICENSE-2.0).
-Pulsar Committers will review those translations. If your translations are not
reviewed or approved by any committers,
-feel free to reach out to use via [slack
channel](https://apache-pulsar.herokuapp.com/) or [mailing
lists](https://pulsar.apache.org/contact/).
+Translation you contribute is licensed under [Apache License
V2](https://www.apache.org/licenses/LICENSE-2.0).
+Pulsar Committers will review translation. If your translation is not reviewed
or approved by any committer,
+feel free to reach out via [slack
channel](https://apache-pulsar.herokuapp.com/) or [mailing
lists](https://pulsar.apache.org/contact/).
\ No newline at end of file
