Skip to content

Commit

Permalink
[Doc] Update the site2/README.md file (apache#4130)
Browse files Browse the repository at this point in the history 
### 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.
  • Loading branch information
@Jennifer88huang-zz @sijie
Jennifer88huang-zz authored and sijie committed Apr 26, 2019
1 parent 5f0242e commit c1b8442
Showing 1 changed file with 48 additions and 50 deletions.
98 changes: 48 additions & 50 deletions site2/README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -67,24 +68,24 @@ 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.

#### Document

##### 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:

Expand All @@ -98,58 +99,58 @@ 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:

```md
[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:

```shell
{@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
{
Expand All @@ -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

Expand All @@ -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/).

0 comments on commit c1b8442

Please sign in to comment.