From a66e7adfe0baab12ec3aa3cdaf8f609d58a83354 Mon Sep 17 00:00:00 2001
From: Yuwen Hu <54161268+Oscilloscope98@users.noreply.github.com>
Date: Mon, 24 Oct 2022 17:40:46 +0800
Subject: [PATCH] [Doc] Update README.md in `docs/readthedocs` folder (#6245)

* Update requirements-rtd.txt for local build consistent with readthedocs deployment

* Update doc readme for local building

* Small revision

* Small typo fixes
---
 docs/readthedocs/README.md            | 34 ++++++++++++++++++++++-----
 docs/readthedocs/requirements-rtd.txt | 16 +++++--------
 2 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/docs/readthedocs/README.md b/docs/readthedocs/README.md
index faedc5cb..8c2d8b2b 100644
--- a/docs/readthedocs/README.md
+++ b/docs/readthedocs/README.md
@@ -1,15 +1,37 @@
 # BigDL Documentation
+This is the repository for BigDL documentation, which is hosted at https://bigdl.readthedocs.io/en/latest/
+## Local build
+### 1. Set up environment
+To build BigDL documentation locally for testing purposes, it is recommended to create a conda environment with specified Python version:
 
-To compile the documentation, run the following commands from this directory.
-
+```bash
+conda create -n docs python=3.7
+conda activate docs
 ```
+
+Then inside [`BigDL/docs/readthedocs`](.) folder, install required packages:
+
+```bash
+pip install --upgrade -r requirements-rtd.txt
 pip install -r requirements-doc.txt
-pip install -U -r requirements-rtd.txt # important for reproducing the deployment environment
+```
+> **Note**: `requirements-rtd.txt` is for reproducing ReadtheDocs deployment environment. No need to modify this file when adding new sphinx extension for our documentation. New packages should be added in `requirements-doc.txt`.
+
+### 2. Build the documentation
+You can then build the documentation locally through:
+```bash
 make html
-open _build/html/index.html
 ```
+> **Tips**: If you meet building error `Notebook error: Pandoc wasn't found`, try `conda install pandoc` to resolve it.
 
-To test if there are any build errors with the documentation, do the following.
+> **Note**: The built files inside `docs/readthedocs/_build/html` dictionary should not be committed, they are only for testing purposes.
 
+### 3. Test the documentation
+To view the documentation locally, you could set up a testing server:
+```bash
+cd _build/html
+python -m http.server 8000
 ```
-sphinx-build -b html -d _build/doctrees source _build/html
+The documentation can then be reached at [http://localhost:8000/](http://localhost:8000/).
+
+> **Note**: If you are setting up the testing server on a remote machine, it is recommended to forward port `8000` through VSCode, so that you could reach [http://localhost:8000/](http://localhost:8000/) normally as on your local machine.
\ No newline at end of file
diff --git a/docs/readthedocs/requirements-rtd.txt b/docs/readthedocs/requirements-rtd.txt
index f90939b6..9e1c4005 100644
--- a/docs/readthedocs/requirements-rtd.txt
+++ b/docs/readthedocs/requirements-rtd.txt
@@ -1,13 +1,9 @@
-Pygments==2.3.1
-setuptools==41.0.1
-docutils==0.14
+setuptools<58.3.0
+pillow
 mock==1.0.1
-pillow==5.4.1
 alabaster>=0.7,<0.8,!=0.7.5
-commonmark==0.8.1
+commonmark==0.9.1
 recommonmark==0.5.0
-readthedocs-sphinx-ext<1.1
-markdown<3.4
-sphinx-book-theme
-sphinx_rtd_theme==1.0.0
-sphinx_markdown_tables==0.0.15
+sphinx
+sphinx-rtd-theme
+readthedocs-sphinx-ext<2.2
\ No newline at end of file