a66e7adfe0
* Update requirements-rtd.txt for local build consistent with readthedocs deployment * Update doc readme for local building * Small revision * Small typo fixes
37 lines
No EOL
1.6 KiB
Markdown
37 lines
No EOL
1.6 KiB
Markdown
# 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:
|
|
|
|
```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
|
|
```
|
|
> **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
|
|
```
|
|
> **Tips**: If you meet building error `Notebook error: Pandoc wasn't found`, try `conda install pandoc` to resolve it.
|
|
|
|
> **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
|
|
```
|
|
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. |