[ci] [docs] use miniforge for readthedocs builds (fixes #4954)

.ci/test.sh

@@ -29,15 +29,23 @@ if [[ "$TASK" == "cpp-tests" ]]; then
     exit 0
 fi
 
-conda create -q -y -n $CONDA_ENV python=$PYTHON_VERSION
-source activate $CONDA_ENV
-
 cd $BUILD_DIRECTORY
 
 if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then
     cd $BUILD_DIRECTORY/docs
-    conda install -q -y -n $CONDA_ENV -c conda-forge doxygen rstcheck
-    pip install --user -r requirements.txt
+    conda env create \
+        -q \
+        -n docs-env \
+        -f ./env.yml
+    conda install \
+        -q \
+        -y \
+        -n docs-env \
+        -c conda-forge \
+        --override-channels \
+            doxygen \
+            rstcheck
+    source activate docs-env
     # check reStructuredText formatting
     cd $BUILD_DIRECTORY/python-package
     rstcheck --report warning $(find . -type f -name "*.rst") || exit -1
@@ -60,6 +68,9 @@ if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then
     exit 0
 fi
 
+conda create -q -y -n $CONDA_ENV python=$PYTHON_VERSION
+source activate $CONDA_ENV
+
 if [[ $TASK == "lint" ]]; then
     conda install -q -y -n $CONDA_ENV \
         pycodestyle \

.gitignore

@@ -346,6 +346,7 @@ instance/
 # Sphinx documentation
 docs/_build/
 docs/pythonapi/
+*.flag
 
 # Doxygen documentation
 docs/doxyoutput/

.readthedocs.yaml

@@ -1,10 +1,12 @@
 version: 2
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "mambaforge-4.10"
+conda:
+  environment: docs/env.yml
 formats:
   - pdf
-python:
-  version: 3
-  install:
-    - requirements: docs/requirements.txt
 sphinx:
   builder: html
   configuration: docs/conf.py

docs/README.rst

@@ -13,11 +13,46 @@ After each commit on ``master``, documentation is updated and published to `Read
 Build
 -----
 
+It is not necessary to re-build this documentation while modifying LightGBM's source code.
+The HTML files generated using ``Sphinx`` are not checked into source control.
+However, you may want to build them locally during development to test changes.
+
+Docker
+^^^^^^
+
+The most reliable way to build the documentation locally is with Docker, using `the same images readthedocs uses <https://hub.docker.com/r/readthedocs/build>`_.
+
+Run the following from the root of this repository to pull the relevant image and run a container locally.
+
+.. code:: sh
+
+    docker run \
+        --rm \
+        --user=0 \
+        -v $(pwd):/opt/LightGBM \
+        --env C_API=true \
+        --env CONDA=/opt/conda \
+        --env PYTHONUNBUFFERED=1 \
+        --env READTHEDOCS=true \
+        --workdir=/opt/LightGBM/docs \
+        --entrypoint="" \
+        -it readthedocs/build:ubuntu-20.04-2021.09.23 \
+        /bin/bash build-docs.sh
+
+When that code completes, open ``docs/html/index.html`` in your browser.
+
+.. note::
+
+    The navigation in locally-built docs does not link to the local copy of the R documentation. To view the local version of the R docs, open ``docs/_build/html/R/index.html`` in your browser.
+
+Locally
+^^^^^^^
+
 You can build the documentation locally. Just install Doxygen and run in ``docs`` folder
 
 .. code:: sh
 
-    pip install -r requirements.txt
+    pip install breathe sphinx 'sphinx_rtd_theme>0.5'
     make html
 
 Unfortunately, documentation for R code is built only on our site, and commands above will not build it for you locally.

docs/build-docs.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+rm -f ./_FIRST_RUN.flag
+
+ARCH=$(uname -m)
+export PATH="${CONDA}/bin:${PATH}"
+
+curl \
+    -L \
+    -o ${HOME}/conda.sh \
+    "https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-${ARCH}.sh"
+
+/bin/bash ${HOME}/conda.sh -b -p ${CONDA}
+
+conda config --set always_yes yes --set changeps1 no
+
+mamba env create \
+    --name docs-env \
+    --file env.yml || exit -1
+
+source activate docs-env
+
+${CONDA}/envs/docs-env/bin/python \
+    -m sphinx \
+    -T \
+    -E \
+    -W \
+    --keep-going \
+    -b html \
+    -d _build/doctrees \
+    -D language=en \
+    . _build/html || exit -1
+
+echo "Done building docs. Open docs/_build/html/index.html in a web browser to view them."

docs/conf.py

@@ -259,21 +259,6 @@ def generate_r_docs(app: Sphinx) -> None:
         The application object representing the Sphinx process.
     """
     commands = f"""
-    /home/docs/.conda/bin/conda create \
-        -q \
-        -y \
-        -c conda-forge \
-        --override-channels \
-        -n r_env \
-            r-base=4.1.0=hb67fd72_2 \
-            r-data.table=1.14.0=r41hcfec24a_0 \
-            r-jsonlite=1.7.2=r41hcfec24a_0 \
-            r-knitr=1.35=r41hc72bb7e_0 \
-            r-matrix=1.3_4=r41he454529_0 \
-            r-pkgdown=1.6.1=r41hc72bb7e_0 \
-            r-rmarkdown=2.11=r41hc72bb7e_0 \
-            r-roxygen2=7.1.1=r41h03ef668_0
-    source /home/docs/.conda/bin/activate r_env
     export TAR=/bin/tar
     cd {CURR_PATH.parent}
     export R_LIBS="$CONDA_PREFIX/lib/R/library"
@@ -298,6 +283,7 @@ def generate_r_docs(app: Sphinx) -> None:
     cd {CURR_PATH.parent}
     """
     try:
+        print("Building R-package documentation")
         # Warning! The following code can cause buffer overflows on RTD.
         # Consider suppressing output completely if RTD project silently fails.
         # Refer to https://github.com/svenevs/exhale
@@ -311,6 +297,7 @@ def generate_r_docs(app: Sphinx) -> None:
             raise RuntimeError(output)
         else:
             print(output)
+            print("Done building R-package documentation")
     except BaseException as e:
         raise Exception(f"An error has occurred while generating documentation for R-package\n{e}")
 

docs/env.yml

@@ -0,0 +1,17 @@
+name: docs-env
+channels:
+  - conda-forge
+dependencies:
+  - breathe
+  - python=3.9
+  - pip
+  - r-base=4.1.2
+  - r-data.table=1.14.2
+  - r-jsonlite=1.7.2
+  - r-knitr=1.37
+  - r-matrix=1.4_0
+  - r-pkgdown=1.6.1
+  - r-rmarkdown=2.11
+  - r-roxygen2=7.1.2
+  - sphinx
+  - "sphinx_rtd_theme>=0.5"