42 lines
No EOL
2 KiB
Markdown
42 lines
No EOL
2 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
|
|
cd docs/readthedocs
|
|
# for reproducing ReadtheDocs deployment environment
|
|
pip install --upgrade pip "setuptools<58.3.0"
|
|
pip install --upgrade pillow mock==1.0.1 "alabaster>=0.7,<0.8,!=0.7.5" commonmark==0.9.1 recommonmark==0.5.0 sphinx sphinx-rtd-theme "readthedocs-sphinx-ext<2.3"
|
|
|
|
# for other documentation related dependencies
|
|
wget https://raw.githubusercontent.com/analytics-zoo/gha-cicd-env/main/python-requirements/requirements-doc.txt
|
|
pip install -r requirements-doc.txt
|
|
```
|
|
> **Note**: When adding new sphinx extensions for our documentation, the requirements file located [here](https://raw.githubusercontent.com/analytics-zoo/gha-cicd-env/main/python-requrirements/requirements-doc.txt) should be modified.
|
|
### 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. |