You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by li...@apache.org on 2023/02/03 02:19:42 UTC
[pulsar-site] branch main updated: docs: contributing runbook (#396)
This is an automated email from the ASF dual-hosted git repository.
liuyu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new 7a89555be28 docs: contributing runbook (#396)
7a89555be28 is described below
commit 7a89555be28d57875272129ace36879232014be1
Author: tison <wa...@gmail.com>
AuthorDate: Fri Feb 3 10:19:36 2023 +0800
docs: contributing runbook (#396)
---
contribute/document-preview.md | 5 +-
contribute/document-syntax.md | 2 +-
contribute/site-intro.md | 110 +++++++++++++++++++++++++++++++++++++++++
sidebarsDevelopment.js | 11 ++++-
4 files changed, 121 insertions(+), 7 deletions(-)
diff --git a/contribute/document-preview.md b/contribute/document-preview.md
index 61db1347532..aef473115f7 100644
--- a/contribute/document-preview.md
+++ b/contribute/document-preview.md
@@ -1,7 +1,4 @@
----
-id: document-preview
-title: Previewing content
----
+# Previewing content
This guide explains why and how to preview Pulsar content locally with detailed steps and various examples.
diff --git a/contribute/document-syntax.md b/contribute/document-syntax.md
index f31f01e2327..f767c129fc3 100644
--- a/contribute/document-syntax.md
+++ b/contribute/document-syntax.md
@@ -1,6 +1,6 @@
---
id: document-syntax
-title: Writing syntax guide
+title: Writing syntax
---
````mdx-code-block
diff --git a/contribute/site-intro.md b/contribute/site-intro.md
new file mode 100644
index 00000000000..7c1a3db2270
--- /dev/null
+++ b/contribute/site-intro.md
@@ -0,0 +1,110 @@
+# Introduction
+
+The Pulsar site is built with [Docusaurus](http://docusaurus.io/) framework. You can find all technical details on [its docs](https://docusaurus.io/docs).
+
+Specifically, this chapter provides a [writing syntax](document-syntax.md) guide selecting knowledge for writing content of the site.
+
+## Source
+
+Currently, the source of the site is located at the [apache/pulsar-site](http://github.com/apache/pulsar-site) repo.
+
+## Pages
+
+Docusaurus provides three kinds of pages out-of-the-box: [docs](https://docusaurus.io/docs/docs-introduction), [blogs](https://docusaurus.io/docs/blog), and [JSX pages](https://docusaurus.io/docs/creating-pages).
+
+The Pulsar site pages are of:
+
+| Page | Type | Source |
+|--------------------------------------------|-----------|---------------------------------------------------------------------------------------------------|
+| [User docs](pathname:///docs) | docs | <ul><li>docs/</li><li>versioned_docs/</li><li>versioned_sidebars/</li><li>sidebars.json</li></ul> |
+| [Contribution guides](about.md) | docs | <ul><li>contribute/</li><li>sidebarsDevelopment.js</li></ul> |
+| [Release notes](pathname:///release-notes) | docs | <ul><li>release-notes/</li><li>sidebarsReleaseNotes.js</li></ul> |
+| [Security](pathname:///security) | docs | <ul><li>security/</li></ul> |
+| [Blogs](pathname:///blog) | blog | <ul><li>blog/</li></ul> |
+| Other pages | JSX pages | <ul><li>src/pages/</li></ul> |
+
+Besides, the site serves multiple static pages generated outside the framework, including API docs, reference docs, and swagger files. You can find them under the `static` folder.
+
+## Tools
+
+### preview.sh
+
+The most commonly used tool is `preview.sh`. You can preview your local changes by:
+
+```shell
+./preview.sh 2.11.x
+```
+
+See the [previewing content](document-preview.md) guide for more details.
+
+### docker-compose.yaml
+
+The `preview.sh` script use the Docusaurus dev server for testing, which is different from the real Apache Web Server based env that serves the site online.
+
+To emulate the server-side logics, like `.htaccess` rewrite rules, you can run:
+
+```shell
+yarn build
+docker-compose up
+```
+
+### Pytools
+
+The site repo has a set of Python scripts for generating content and syncing/updating/publishing the site.
+
+You can read the [README](https://github.com/apache/pulsar-site/tree/main/tools/pytools/README.md) file of pytools for details.
+
+## How-tos
+
+This section holds common how-tos about website maintenance and troubleshooting.
+
+### How to fix search index mismatches?
+
+First of all, you should get permission to access `apache_pulsar` crawler on [Algolia Crawler console](https://crawler.algolia.com/). You can email dev@pulsar.apache.org to ask for permission.
+
+The most common fix for search index mismatches is to re-index the pages. You can do so by clicking "Restart crawling" button on the [crawler page](https://crawler.algolia.com/admin/crawlers/7a3458ba-2373-47d5-9520-90cc9cc10736/overview). Typically, it takes about 1 or 2 hours to complete.
+
+### How to preview changes locally?
+
+If you make any changes to the site, before submitting a pull request, you're supposed to preview the changes locally. Read the [previewing content](document-preview.md) guide about instructions.
+
+### How to update reference pages?
+
+If you're gonna to update the content, read the [update reference docs](document-contribution.md#update-reference-docs) guide about the sources of reference pages.
+
+If you're gonna to debug the reference generation process, read the [reference-doc-generator](https://github.com/apache/pulsar-site/tree/main/tools/pytools#reference-doc-generator) usage section and its source code.
+
+### How to update data driven pages?
+
+The following pages contain data-driven tables:
+
+* [Case studies](pathname:///case-studies)
+ * data/users.js
+ * src/pages/case-studies.js
+* [Downloads](pathname:///download)
+ * releases.json
+ * data/connectors.js
+ * data/release-cpp.js
+ * data/release-pulsar-manager.js
+ * data/release-pulsar-adapters.js
+ * src/components/download.tsx
+ * src/pages/download.mdx
+* [Ecosystem](pathname:///ecosystem)
+ * data/ecosystem.js
+ * src/pages/ecosystem.js
+* [Events](pathname:///events)
+ * data/events.js
+ * src/pages/events.js
+* [Release notes](pathname:///release-notes)
+ * data/release-*.js
+ * release-notes/
+ * src/components/ClientReleaseTable.js
+ * src/components/PulsarReleaseTable.js
+* [Resources](pathname:///resources)
+ * data/resources.js
+ * src/pages/resources.js
+* [Team](pathname:///team)
+ * data/team.js
+ * src/pages/team.js
+
+Additionally, PMC members can generate the `team.js` file as @lhotari did in https://github.com/apache/pulsar-site/pull/387.
diff --git a/sidebarsDevelopment.js b/sidebarsDevelopment.js
index eb90ece8044..4a994137239 100644
--- a/sidebarsDevelopment.js
+++ b/sidebarsDevelopment.js
@@ -27,14 +27,21 @@ const sidebars = {
'personal-ci',
]
},
+ {
+ type: "category",
+ label: "Website",
+ items: [
+ 'site-intro',
+ 'document-preview',
+ 'document-syntax',
+ ]
+ },
{
type: "category",
label: "Documentation",
items: [
'document-intro',
'document-contribution',
- 'document-preview',
- 'document-syntax',
]
},
{