diff --git a/.ci/test.sh b/.ci/test.sh index c94151ac1e51..9e6bf0085ea2 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -36,8 +36,15 @@ 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 update \ + -n $CONDA_ENV \ + --file ./env.yml || exit -1 + conda install \ + -q \ + -y \ + -n $CONDA_ENV \ + doxygen \ + rstcheck || exit -1 # check reStructuredText formatting cd $BUILD_DIRECTORY/python-package rstcheck --report warning $(find . -type f -name "*.rst") || exit -1 diff --git a/.gitignore b/.gitignore index 96e0700f4f49..bb65ca426bba 100644 --- a/.gitignore +++ b/.gitignore @@ -346,6 +346,7 @@ instance/ # Sphinx documentation docs/_build/ docs/pythonapi/ +*.flag # Doxygen documentation docs/doxyoutput/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 4f85742c7f74..7d63476a0f79 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,10 +1,12 @@ version: 2 +build: + os: "ubuntu-20.04" + tools: + python: "miniconda3-4.7" +conda: + environment: docs/env.yml formats: - pdf -python: - version: 3 - install: - - requirements: docs/requirements.txt sphinx: builder: html configuration: docs/conf.py diff --git a/docs/README.rst b/docs/README.rst index e41fe8803715..7ce36aed1d95 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -13,20 +13,55 @@ After each commit on ``master``, documentation is updated and published to `Read Build ----- -You can build the documentation locally. Just install Doxygen and run in ``docs`` folder +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 Read the Docs uses `_. + +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/miniforge \ + --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/_build/html/index.html`` in your browser. + +.. note:: + + The navigation in these 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. + +Without Docker +^^^^^^^^^^^^^^ + +You can build the documentation locally without Docker. 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. +Note that this will not build the R documentation. Consider using common R utilities for documentation generation, if you need it. +Or use the Docker-based approach described above to build the R documentation locally. If you faced any problems with Doxygen installation or you simply do not need documentation for C code, it is possible to build the documentation without it: .. code:: sh - pip install -r requirements_base.txt + pip install sphinx 'sphinx_rtd_theme>=0.5' export C_API=NO || set C_API=NO make html diff --git a/docs/build-docs.sh b/docs/build-docs.sh new file mode 100644 index 000000000000..689a30df9962 --- /dev/null +++ b/docs/build-docs.sh @@ -0,0 +1,24 @@ +#!/bin/bash + +rm -f ./_FIRST_RUN.flag + +export PATH="${CONDA}/bin:${PATH}" + +curl \ + -sL \ + -o ${HOME}/miniforge.sh \ + https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh + +/bin/bash ${HOME}/miniforge.sh -b -p ${CONDA} + +conda config --set always_yes yes --set changeps1 no +conda update -q -y conda + +conda env create \ + --name docs-env \ + --file env.yml || exit -1 + +source activate docs-env +make clean html || exit -1 + +echo "Done building docs. Open docs/_build/html/index.html in a web browser to view them." diff --git a/docs/conf.py b/docs/conf.py index 0c2a5d183c82..ce13e6801ae6 100644 --- a/docs/conf.py +++ b/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}") diff --git a/docs/env.yml b/docs/env.yml new file mode 100644 index 000000000000..a5b1b80e4f69 --- /dev/null +++ b/docs/env.yml @@ -0,0 +1,17 @@ +name: docs-env +channels: + - nodefaults + - conda-forge +dependencies: + - breathe + - python=3.9 + - 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" diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 17896e0c7283..000000000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ --r requirements_base.txt -breathe diff --git a/docs/requirements_base.txt b/docs/requirements_base.txt deleted file mode 100644 index baebc41b5e1c..000000000000 --- a/docs/requirements_base.txt +++ /dev/null @@ -1,2 +0,0 @@ -sphinx -sphinx_rtd_theme >= 0.5