From 730ab69b24ae7c6a3220b086f7970806dd823099 Mon Sep 17 00:00:00 2001 From: Shawn Yan Date: Fri, 12 Jan 2024 14:33:42 +0800 Subject: [PATCH 01/10] resource: add tidb-pdf-generation-tutorial.md --- README.md | 2 + resources/tidb-pdf-generation-tutorial.md | 120 ++++++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 resources/tidb-pdf-generation-tutorial.md diff --git a/README.md b/README.md index a54701d2fffba..48384a2a996d1 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ This repository stores all the source files of [TiDB Docs at the PingCAP website If you find documentation issues, feel free to [create an Issue](https://github.com/pingcap/docs/issues/new/choose) to let us know or directly [create a Pull Request](/CONTRIBUTING.md#how-to-contribute) to help fix or update it. +If you want to locally customize and output TiDB Documentation in PDF format that meet the needs of specific scenarios, such as freely sorting or deleting the contents of TiDB Documentation, please refer to [Self-service generation of TiDB document PDF tutorial](/resources/tidb-pdf-generation-tutorial.md). + Currently, the official documentation supports two languages: - `en`: [documentation in English](https://docs.pingcap.com/tidb/stable) diff --git a/resources/tidb-pdf-generation-tutorial.md b/resources/tidb-pdf-generation-tutorial.md new file mode 100644 index 0000000000000..b6da873a7665e --- /dev/null +++ b/resources/tidb-pdf-generation-tutorial.md @@ -0,0 +1,120 @@ +--- +title: Self-service generation of TiDB Documentation PDF tutorial +summary: Learn how to locally customize the output of TiDB Documentation PDF that meets the needs of specific scenarios. +--- + +# Self-service generation of TiDB Documentation PDF tutorial + +This tutorial provides a method to self-generate TiDB documents in PDF format. Through this method, you can freely sort and delete the contents of TiDB Documentation locally, and customize the output to PDF that meets the needs of specific scenarios. + +## Environment preparation + +The following preparations only need to be performed when generating a PDF file for the first time and can be skipped directly when generating again in the future. + +### Preparation 1: Install and configure the Docker environment + +> Estimated time: 30 minutes. + +The following uses macOS or Windows as an example to install Docker Desktop. + +1. Install [Docker Desktop](https://docs.docker.com/get-docker/)。 + +2. Run the `docker --version` command in macOS Terminal or Windows PowerShell. + + If you see the Docker version information, the installation is successful. + +3. Configure Docker resources. + + 1. Open the Docker application and click the gear icon in the upper-right corner. + 2. Click **Resources** and set **Memory** to `8.00 GB`. + +4. Run the following command in macOS Terminal or Windows PowerShell to pull the Docker image used for TiDB PDF document construction: + + ```bash + docker pull andelf/doc-build:0.1.9 + ``` + +### Preparation 2: Clone the TiDB Documentation repository to local + +> Estimated time: 10 minutes. + +TiDB Documentation in Chinese repository: , TiDB Documentation in English repository: . + +Follow the steps to clone the TiDB Documentation in English as an example: + +1. Open TiDB Documentation repository: 。 + +2. Click [**Fork**](https://github.com/pingcap/docs/fork) in the upper-right corner, and wait for the Fork to complete. + +3. Use any of the following methods to clone the TiDB Documentation repository locally. + + - Method 1: Use GitHub Desktop client. + + 1. Install and launch [GitHub Desktop](https://desktop.github.com/). + 2. In the GitHub Desktop, click **File** > **Clone Repository**. + 3. Click the **GitHub.com** tab and select **Your Repositories**, then select the repository you forked, click **Clone** in the lower-right corner. + + - Method 2: Use the following `Git` command. + + ```shell + cd $working_dir # Replace `$working_dir` with the directory where you want the repository to be placed. For example, `cd ~/Documents/GitHub` + git clone git@github.com:$user/docs.git # Replace `$user` with your GitHub ID + + cd $working_dir/docs + git remote add upstream git@github.com:pingcap/docs.git # Add upstream repository + git remote -v + ``` + +## Steps + +> Estimated time: The operation only takes 2 minutes, and the PDF generation needs to wait 0.5 to 1 hour. + +1. Make sure that the files in your local TiDB Documentation repository are the latest versions in the upstream GitHub repository. + +2. Freely sort or delete the contents of TiDB Documentation according to your needs. + + 1. Open the `TOC.md` file located in the root directory of your local repository. + 2. Edit the `TOC.md` file. For example, you can remove all unnecessary document chapters titles, and links. + +3. Consolidate chapters from all documents into one Markdown file according to the `TOC.md` file. + + 1. Start the Docker application. + 2. Run the following command in macOS Terminal or Windows PowerShell, to enter the Docker image for PDF document building: + + ```bash + docker run -it -v ${doc-path}:/opt/data andelf/doc-build:0.1.9 + ``` + + Among them, `${doc-path}` is the path of your local folder of the document to be generated. For example, if the path is `/Users/${username}/Documents/GitHub/docs`, the command is: + + ```bash + docker run -it -v /Users/${username}/Documents/GitHub/docs:/opt/data andelf/doc-build:0.1.9 + ``` + + After execution, if there is a warning `WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested`, you can ignore it. + + 3. Enter the `opt/data` directory. + + ```bash + cd /opt/data + ``` + + 4. Consolidate all Markdown document files into one `doc.md` file according to `TOC.md`. + + ```bash + python3 scripts/merge_by_toc.py + ``` + + **Expected output:** + + In the same folder as `TOC.md`, you will see a newly generated `doc.md` file. + +4. Generate document PDF: + + ```bash + bash scripts/generate_pdf.sh + ``` + + **Expected output:** + + The time required to generate the PDF is related to the size of the document. For the complete TiDB documentation, it takes about 1 hour. After the generation is completed, you will see the newly generated PDF file `output.pdf` in the folder where the document is located. From 3ddb71188738324e9595eab3cc026ae331641dd4 Mon Sep 17 00:00:00 2001 From: Shawn Yan Date: Mon, 22 Jan 2024 09:41:40 +0800 Subject: [PATCH 02/10] Update README.md Co-authored-by: Grace Cai --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 48384a2a996d1..71e41ba819e0e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ This repository stores all the source files of [TiDB Docs at the PingCAP website If you find documentation issues, feel free to [create an Issue](https://github.com/pingcap/docs/issues/new/choose) to let us know or directly [create a Pull Request](/CONTRIBUTING.md#how-to-contribute) to help fix or update it. -If you want to locally customize and output TiDB Documentation in PDF format that meet the needs of specific scenarios, such as freely sorting or deleting the contents of TiDB Documentation, please refer to [Self-service generation of TiDB document PDF tutorial](/resources/tidb-pdf-generation-tutorial.md). +If you want to locally customize and output TiDB documentation in the PDF format to meet the needs of specific scenarios, such as freely sorting or deleting certain contents in TiDB documentation, please refer to [TiDB Documentation PDF Generation Tutorial](/resources/tidb-pdf-generation-tutorial.md). Currently, the official documentation supports two languages: From 8c2d2760111d5d2de8a0e8f1373925feec29e05f Mon Sep 17 00:00:00 2001 From: Shawn Yan Date: Mon, 22 Jan 2024 09:42:10 +0800 Subject: [PATCH 03/10] Update resources/tidb-pdf-generation-tutorial.md Co-authored-by: Grace Cai --- resources/tidb-pdf-generation-tutorial.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/resources/tidb-pdf-generation-tutorial.md b/resources/tidb-pdf-generation-tutorial.md index b6da873a7665e..4ed652020f0a1 100644 --- a/resources/tidb-pdf-generation-tutorial.md +++ b/resources/tidb-pdf-generation-tutorial.md @@ -5,7 +5,8 @@ summary: Learn how to locally customize the output of TiDB Documentation PDF tha # Self-service generation of TiDB Documentation PDF tutorial -This tutorial provides a method to self-generate TiDB documents in PDF format. Through this method, you can freely sort and delete the contents of TiDB Documentation locally, and customize the output to PDF that meets the needs of specific scenarios. +This tutorial provides a method to generate TiDB documentation in PDF format. With this method, you can freely sort and delete certain contents in TiDB Documentation locally, and customize the PDF output to meet the needs of specific scenarios. + ## Environment preparation From 5f9dded5dcadd76d3f39a74a056020b8b8035467 Mon Sep 17 00:00:00 2001 From: Shawn Yan Date: Mon, 22 Jan 2024 09:48:38 +0800 Subject: [PATCH 04/10] Apply suggestions from code review Co-authored-by: Grace Cai --- resources/tidb-pdf-generation-tutorial.md | 71 ++++++++++++++--------- 1 file changed, 45 insertions(+), 26 deletions(-) diff --git a/resources/tidb-pdf-generation-tutorial.md b/resources/tidb-pdf-generation-tutorial.md index 4ed652020f0a1..6faab15cf186a 100644 --- a/resources/tidb-pdf-generation-tutorial.md +++ b/resources/tidb-pdf-generation-tutorial.md @@ -1,24 +1,27 @@ --- -title: Self-service generation of TiDB Documentation PDF tutorial -summary: Learn how to locally customize the output of TiDB Documentation PDF that meets the needs of specific scenarios. +title: TiDB Documentation PDF Generation Tutorial +summary: Learn how to locally customize the PDF output of TiDB Documentation to meet the needs of specific scenarios. --- -# Self-service generation of TiDB Documentation PDF tutorial +# TiDB Documentation PDF Generation Tutorial This tutorial provides a method to generate TiDB documentation in PDF format. With this method, you can freely sort and delete certain contents in TiDB Documentation locally, and customize the PDF output to meet the needs of specific scenarios. ## Environment preparation -The following preparations only need to be performed when generating a PDF file for the first time and can be skipped directly when generating again in the future. +The following preparations only need to be performed once when you generate a PDF file for the first time and can be skipped directly for future PDF generations. + ### Preparation 1: Install and configure the Docker environment > Estimated time: 30 minutes. -The following uses macOS or Windows as an example to install Docker Desktop. +The following steps take macOS or Windows as an example for Docker Desktop installation. + + +1. Install [Docker Desktop](https://docs.docker.com/get-docker/). -1. Install [Docker Desktop](https://docs.docker.com/get-docker/)。 2. Run the `docker --version` command in macOS Terminal or Windows PowerShell. @@ -26,36 +29,43 @@ The following uses macOS or Windows as an example to install Docker Desktop. 3. Configure Docker resources. - 1. Open the Docker application and click the gear icon in the upper-right corner. + 1. Launch the Docker application and click the gear icon in the upper-right corner. + 2. Click **Resources** and set **Memory** to `8.00 GB`. -4. Run the following command in macOS Terminal or Windows PowerShell to pull the Docker image used for TiDB PDF document construction: +4. Run the following command in macOS Terminal or Windows PowerShell to pull the Docker image used for building TiDB PDF documentation: + ```bash docker pull andelf/doc-build:0.1.9 ``` -### Preparation 2: Clone the TiDB Documentation repository to local +### Preparation 2: Clone the TiDB documentation repository to your local disk + > Estimated time: 10 minutes. -TiDB Documentation in Chinese repository: , TiDB Documentation in English repository: . +TiDB English documentation repository: ; TiDB Chinese documentation repository: + + +The following steps take TiDB English documentation as an example to show how to clone the repository: -Follow the steps to clone the TiDB Documentation in English as an example: +1. Go to the TiDB English documentation repository: . -1. Open TiDB Documentation repository: 。 2. Click [**Fork**](https://github.com/pingcap/docs/fork) in the upper-right corner, and wait for the Fork to complete. -3. Use any of the following methods to clone the TiDB Documentation repository locally. +3. Use either of the following methods to clone the TiDB documentation repository locally. - Method 1: Use GitHub Desktop client. 1. Install and launch [GitHub Desktop](https://desktop.github.com/). - 2. In the GitHub Desktop, click **File** > **Clone Repository**. - 3. Click the **GitHub.com** tab and select **Your Repositories**, then select the repository you forked, click **Clone** in the lower-right corner. + 2. In GitHub Desktop, click **File** > **Clone Repository**. + + 3. Click the **GitHub.com** tab, select the repository you forked in **Your Repositories**, and then click **Clone** in the lower-right corner. + + - Method 2: Use the following `Git` commands. - - Method 2: Use the following `Git` command. ```shell cd $working_dir # Replace `$working_dir` with the directory where you want the repository to be placed. For example, `cd ~/Documents/GitHub` @@ -68,33 +78,40 @@ Follow the steps to clone the TiDB Documentation in English as an example: ## Steps -> Estimated time: The operation only takes 2 minutes, and the PDF generation needs to wait 0.5 to 1 hour. +> Estimated time: The following operations only take two minutes, but the PDF generation requires waiting for 0.5 to 1 hour. -1. Make sure that the files in your local TiDB Documentation repository are the latest versions in the upstream GitHub repository. -2. Freely sort or delete the contents of TiDB Documentation according to your needs. +1. Make sure that the files in your local TiDB documentation repository are the latest versions in the upstream GitHub repository. + +2. Freely sort or delete the contents in TiDB Documentation according to your needs. + 1. Open the `TOC.md` file located in the root directory of your local repository. - 2. Edit the `TOC.md` file. For example, you can remove all unnecessary document chapters titles, and links. + 2. Edit the `TOC.md` file. For example, you can remove all unnecessary document chapters titles and links. + 3. Consolidate chapters from all documents into one Markdown file according to the `TOC.md` file. 1. Start the Docker application. - 2. Run the following command in macOS Terminal or Windows PowerShell, to enter the Docker image for PDF document building: + 2. Run the following command in macOS Terminal or Windows PowerShell, to enter the Docker image for PDF documentation building: + ```bash docker run -it -v ${doc-path}:/opt/data andelf/doc-build:0.1.9 ``` - Among them, `${doc-path}` is the path of your local folder of the document to be generated. For example, if the path is `/Users/${username}/Documents/GitHub/docs`, the command is: + In the command, `${doc-path}` is the local path of the documentation for PDF generation. For example, if the path is `/Users/${username}/Documents/GitHub/docs`, the command is as follows: + ```bash docker run -it -v /Users/${username}/Documents/GitHub/docs:/opt/data andelf/doc-build:0.1.9 ``` - After execution, if there is a warning `WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested`, you can ignore it. + After execution, if `WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested` is returned, you can ignore it. + + + 3. Go to the `opt/data` directory. - 3. Enter the `opt/data` directory. ```bash cd /opt/data @@ -110,7 +127,8 @@ Follow the steps to clone the TiDB Documentation in English as an example: In the same folder as `TOC.md`, you will see a newly generated `doc.md` file. -4. Generate document PDF: +4. Generate the PDF documentation: + ```bash bash scripts/generate_pdf.sh @@ -118,4 +136,5 @@ Follow the steps to clone the TiDB Documentation in English as an example: **Expected output:** - The time required to generate the PDF is related to the size of the document. For the complete TiDB documentation, it takes about 1 hour. After the generation is completed, you will see the newly generated PDF file `output.pdf` in the folder where the document is located. + The time required to generate the PDF file depends on the documentation size. For the complete TiDB documentation, it takes about 1 hour. After the generation is completed, you will see the newly generated PDF file `output.pdf` in the folder where the documentation is located. + From c574f493e30119a105b9f9b424acff51b3306831 Mon Sep 17 00:00:00 2001 From: Shawn Yan Date: Mon, 22 Jan 2024 15:20:31 +0800 Subject: [PATCH 05/10] Update tidb-pdf-generation-tutorial.md --- resources/tidb-pdf-generation-tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resources/tidb-pdf-generation-tutorial.md b/resources/tidb-pdf-generation-tutorial.md index 6faab15cf186a..379a127eadf43 100644 --- a/resources/tidb-pdf-generation-tutorial.md +++ b/resources/tidb-pdf-generation-tutorial.md @@ -64,7 +64,7 @@ The following steps take TiDB English documentation as an example to show how to 3. Click the **GitHub.com** tab, select the repository you forked in **Your Repositories**, and then click **Clone** in the lower-right corner. - - Method 2: Use the following `Git` commands. + - Method 2: Use the following `git` commands. ```shell From 842d5bdc97ec03e757ade836fcff7223e684ac1e Mon Sep 17 00:00:00 2001 From: qiancai Date: Tue, 23 Jan 2024 17:03:45 +0800 Subject: [PATCH 06/10] remove unnecessary empty lines --- resources/tidb-pdf-generation-tutorial.md | 23 +++-------------------- 1 file changed, 3 insertions(+), 20 deletions(-) diff --git a/resources/tidb-pdf-generation-tutorial.md b/resources/tidb-pdf-generation-tutorial.md index 379a127eadf43..e7faa7fbabba0 100644 --- a/resources/tidb-pdf-generation-tutorial.md +++ b/resources/tidb-pdf-generation-tutorial.md @@ -7,11 +7,9 @@ summary: Learn how to locally customize the PDF output of TiDB Documentation to This tutorial provides a method to generate TiDB documentation in PDF format. With this method, you can freely sort and delete certain contents in TiDB Documentation locally, and customize the PDF output to meet the needs of specific scenarios. - ## Environment preparation -The following preparations only need to be performed once when you generate a PDF file for the first time and can be skipped directly for future PDF generations. - +The following preparation steps only need to be performed once when you generate a PDF file for the first time and can be skipped directly for future PDF generations. ### Preparation 1: Install and configure the Docker environment @@ -19,10 +17,8 @@ The following preparations only need to be performed once when you generate a PD The following steps take macOS or Windows as an example for Docker Desktop installation. - 1. Install [Docker Desktop](https://docs.docker.com/get-docker/). - 2. Run the `docker --version` command in macOS Terminal or Windows PowerShell. If you see the Docker version information, the installation is successful. @@ -35,24 +31,20 @@ The following steps take macOS or Windows as an example for Docker Desktop insta 4. Run the following command in macOS Terminal or Windows PowerShell to pull the Docker image used for building TiDB PDF documentation: - ```bash docker pull andelf/doc-build:0.1.9 ``` ### Preparation 2: Clone the TiDB documentation repository to your local disk - > Estimated time: 10 minutes. TiDB English documentation repository: ; TiDB Chinese documentation repository: - The following steps take TiDB English documentation as an example to show how to clone the repository: 1. Go to the TiDB English documentation repository: . - 2. Click [**Fork**](https://github.com/pingcap/docs/fork) in the upper-right corner, and wait for the Fork to complete. 3. Use either of the following methods to clone the TiDB documentation repository locally. @@ -61,12 +53,10 @@ The following steps take TiDB English documentation as an example to show how to 1. Install and launch [GitHub Desktop](https://desktop.github.com/). 2. In GitHub Desktop, click **File** > **Clone Repository**. - 3. Click the **GitHub.com** tab, select the repository you forked in **Your Repositories**, and then click **Clone** in the lower-right corner. - Method 2: Use the following `git` commands. - ```shell cd $working_dir # Replace `$working_dir` with the directory where you want the repository to be placed. For example, `cd ~/Documents/GitHub` git clone git@github.com:$user/docs.git # Replace `$user` with your GitHub ID @@ -80,20 +70,17 @@ The following steps take TiDB English documentation as an example to show how to > Estimated time: The following operations only take two minutes, but the PDF generation requires waiting for 0.5 to 1 hour. - 1. Make sure that the files in your local TiDB documentation repository are the latest versions in the upstream GitHub repository. 2. Freely sort or delete the contents in TiDB Documentation according to your needs. - 1. Open the `TOC.md` file located in the root directory of your local repository. - 2. Edit the `TOC.md` file. For example, you can remove all unnecessary document chapters titles and links. - + 2. Edit the `TOC.md` file. For example, you can remove titles and links of all unnecessary document chapters. 3. Consolidate chapters from all documents into one Markdown file according to the `TOC.md` file. 1. Start the Docker application. - 2. Run the following command in macOS Terminal or Windows PowerShell, to enter the Docker image for PDF documentation building: + 2. Run the following command in macOS Terminal or Windows PowerShell to run the Docker image for PDF documentation building: ```bash @@ -109,10 +96,8 @@ The following steps take TiDB English documentation as an example to show how to After execution, if `WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested` is returned, you can ignore it. - 3. Go to the `opt/data` directory. - ```bash cd /opt/data ``` @@ -129,7 +114,6 @@ The following steps take TiDB English documentation as an example to show how to 4. Generate the PDF documentation: - ```bash bash scripts/generate_pdf.sh ``` @@ -137,4 +121,3 @@ The following steps take TiDB English documentation as an example to show how to **Expected output:** The time required to generate the PDF file depends on the documentation size. For the complete TiDB documentation, it takes about 1 hour. After the generation is completed, you will see the newly generated PDF file `output.pdf` in the folder where the documentation is located. - From 902b1413f047b99bbf7fee7563d0e0ca8c56e291 Mon Sep 17 00:00:00 2001 From: Shawn Yan Date: Wed, 24 Jan 2024 09:09:01 +0800 Subject: [PATCH 07/10] Update tidb-pdf-generation-tutorial.md fix this: ``` [2024-01-23T09:09:05.602Z] resources/tidb-pdf-generation-tutorial.md: 85: MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] [2024-01-23T09:09:05.602Z] resources/tidb-pdf-generation-tutorial.md: 92: MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] ``` --- resources/tidb-pdf-generation-tutorial.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/resources/tidb-pdf-generation-tutorial.md b/resources/tidb-pdf-generation-tutorial.md index e7faa7fbabba0..d68395694bc16 100644 --- a/resources/tidb-pdf-generation-tutorial.md +++ b/resources/tidb-pdf-generation-tutorial.md @@ -82,14 +82,12 @@ The following steps take TiDB English documentation as an example to show how to 1. Start the Docker application. 2. Run the following command in macOS Terminal or Windows PowerShell to run the Docker image for PDF documentation building: - ```bash docker run -it -v ${doc-path}:/opt/data andelf/doc-build:0.1.9 ``` In the command, `${doc-path}` is the local path of the documentation for PDF generation. For example, if the path is `/Users/${username}/Documents/GitHub/docs`, the command is as follows: - ```bash docker run -it -v /Users/${username}/Documents/GitHub/docs:/opt/data andelf/doc-build:0.1.9 ``` From e24ed2a56127f25123f94cba3e44d7a8e9a0ded7 Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Thu, 25 Jan 2024 18:03:47 +0800 Subject: [PATCH 08/10] Update wording and format --- README.md | 2 +- resources/tidb-pdf-generation-tutorial.md | 14 ++++++++------ 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 71e41ba819e0e..5ffc471fd0994 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ This repository stores all the source files of [TiDB Docs at the PingCAP website If you find documentation issues, feel free to [create an Issue](https://github.com/pingcap/docs/issues/new/choose) to let us know or directly [create a Pull Request](/CONTRIBUTING.md#how-to-contribute) to help fix or update it. -If you want to locally customize and output TiDB documentation in the PDF format to meet the needs of specific scenarios, such as freely sorting or deleting certain contents in TiDB documentation, please refer to [TiDB Documentation PDF Generation Tutorial](/resources/tidb-pdf-generation-tutorial.md). +If you want to locally customize and output TiDB documentation in PDF format to meet the needs of specific scenarios, such as freely sorting or deleting certain contents in TiDB documentation, please refer to [TiDB Documentation PDF Generation Tutorial](/resources/tidb-pdf-generation-tutorial.md). Currently, the official documentation supports two languages: diff --git a/resources/tidb-pdf-generation-tutorial.md b/resources/tidb-pdf-generation-tutorial.md index d68395694bc16..2eff07644ff34 100644 --- a/resources/tidb-pdf-generation-tutorial.md +++ b/resources/tidb-pdf-generation-tutorial.md @@ -5,11 +5,13 @@ summary: Learn how to locally customize the PDF output of TiDB Documentation to # TiDB Documentation PDF Generation Tutorial -This tutorial provides a method to generate TiDB documentation in PDF format. With this method, you can freely sort and delete certain contents in TiDB Documentation locally, and customize the PDF output to meet the needs of specific scenarios. +This tutorial provides a method to generate TiDB documentation in PDF format. With this method, you can flexibly sort or delete certain contents in TiDB Documentation locally, and customize the PDF output to meet the needs of specific scenarios. + ## Environment preparation -The following preparation steps only need to be performed once when you generate a PDF file for the first time and can be skipped directly for future PDF generations. +The following preparation steps only need to be performed once when you generate a PDF file for the first time and can be skipped directly for future PDF generation. + ### Preparation 1: Install and configure the Docker environment @@ -70,9 +72,9 @@ The following steps take TiDB English documentation as an example to show how to > Estimated time: The following operations only take two minutes, but the PDF generation requires waiting for 0.5 to 1 hour. -1. Make sure that the files in your local TiDB documentation repository are the latest versions in the upstream GitHub repository. +1. Make sure that the files in your local TiDB documentation repository are of the latest version in the upstream GitHub repository. -2. Freely sort or delete the contents in TiDB Documentation according to your needs. +2. Sort or delete the contents in TiDB Documentation according to your needs. 1. Open the `TOC.md` file located in the root directory of your local repository. 2. Edit the `TOC.md` file. For example, you can remove titles and links of all unnecessary document chapters. @@ -106,9 +108,9 @@ The following steps take TiDB English documentation as an example to show how to python3 scripts/merge_by_toc.py ``` - **Expected output:** + **Expected output:** - In the same folder as `TOC.md`, you will see a newly generated `doc.md` file. + In the same folder as `TOC.md`, you will see a newly generated `doc.md` file. 4. Generate the PDF documentation: From 729920df5c3f7f494aecf366f342201e52fb712b Mon Sep 17 00:00:00 2001 From: Shawn Yan Date: Thu, 25 Jan 2024 20:17:28 +0800 Subject: [PATCH 09/10] Update tidb-pdf-generation-tutorial.md fix this error. ``` [2024-01-25T10:17:03.126Z] resources/tidb-pdf-generation-tutorial.md: 10: MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] [2024-01-25T10:17:03.126Z] resources/tidb-pdf-generation-tutorial.md: 15: MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2] ``` --- resources/tidb-pdf-generation-tutorial.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/resources/tidb-pdf-generation-tutorial.md b/resources/tidb-pdf-generation-tutorial.md index 2eff07644ff34..ea02921c837c1 100644 --- a/resources/tidb-pdf-generation-tutorial.md +++ b/resources/tidb-pdf-generation-tutorial.md @@ -7,12 +7,10 @@ summary: Learn how to locally customize the PDF output of TiDB Documentation to This tutorial provides a method to generate TiDB documentation in PDF format. With this method, you can flexibly sort or delete certain contents in TiDB Documentation locally, and customize the PDF output to meet the needs of specific scenarios. - ## Environment preparation The following preparation steps only need to be performed once when you generate a PDF file for the first time and can be skipped directly for future PDF generation. - ### Preparation 1: Install and configure the Docker environment > Estimated time: 30 minutes. From ce7a07f8186324c01dcce171f8adb4a12f56c13a Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 26 Jan 2024 16:43:48 +0800 Subject: [PATCH 10/10] wording updates --- resources/tidb-pdf-generation-tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resources/tidb-pdf-generation-tutorial.md b/resources/tidb-pdf-generation-tutorial.md index ea02921c837c1..5b438bf97afcf 100644 --- a/resources/tidb-pdf-generation-tutorial.md +++ b/resources/tidb-pdf-generation-tutorial.md @@ -55,7 +55,7 @@ The following steps take TiDB English documentation as an example to show how to 2. In GitHub Desktop, click **File** > **Clone Repository**. 3. Click the **GitHub.com** tab, select the repository you forked in **Your Repositories**, and then click **Clone** in the lower-right corner. - - Method 2: Use the following `git` commands. + - Method 2: Use the following Git commands. ```shell cd $working_dir # Replace `$working_dir` with the directory where you want the repository to be placed. For example, `cd ~/Documents/GitHub`