From bbfa3e51abef379e1056de7316aab91fe175dea8 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Sun, 16 Jan 2022 22:57:29 -0600 Subject: [PATCH 01/18] [ci] [docs] use mamba for readthedocs builds (fixes #4954) --- .readthedocs.yaml | 10 ++++++---- docs/env.yml | 7 +++++++ 2 files changed, 13 insertions(+), 4 deletions(-) create mode 100644 docs/env.yml diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 4f85742c7f74..0e116213080c 100644 --- a/.readthedocs.yaml +++ b/.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 diff --git a/docs/env.yml b/docs/env.yml new file mode 100644 index 000000000000..c7f47238a4c4 --- /dev/null +++ b/docs/env.yml @@ -0,0 +1,7 @@ +name: docs-env +dependencies: + - breathe + - python=3.9 + - pip + - sphinx + - "sphinx_rtd_theme>=0.5" From 4a451bb959bb8dd2f109fb56f58385cd6f2ddb9a Mon Sep 17 00:00:00 2001 From: James Lamb Date: Mon, 17 Jan 2022 09:50:48 -0600 Subject: [PATCH 02/18] update docs --- docs/README.rst | 37 ++++++++++++++++++++++++++++++++++++- docs/build-docs.sh | 36 ++++++++++++++++++++++++++++++++++++ docs/conf.py | 15 --------------- docs/env.yml | 8 ++++++++ 4 files changed, 80 insertions(+), 16 deletions(-) create mode 100644 docs/build-docs.sh diff --git a/docs/README.rst b/docs/README.rst index e41fe8803715..b60081ba6f26 100644 --- a/docs/README.rst +++ b/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 documentatioon 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 `_. + +Run the following from the root of this repository to pull the relevant image and run a container locally. + +.. code:: sh + + docker run \ + --rm \ + -v $(pwd):/opt/LightGBM \ + --env C_API=true \ + --env CONDA=/opt/conda \ + --env PYTHONUNBUFFERED=1 \ + --env READTHEDOCS=true \ + --workdir=/opt/LightGBM/docs \ + --entrypoint="" \ + --user=0 \ + -it readthedocs/build:ubuntu-20.04-2021.09.23 \ + /bin/bash --noprofile --norc 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. diff --git a/docs/build-docs.sh b/docs/build-docs.sh new file mode 100644 index 000000000000..0080252e03aa --- /dev/null +++ b/docs/build-docs.sh @@ -0,0 +1,36 @@ +#!/bin/bash + +set -e -u -o pipefail + +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" + +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 + +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 + +echo "Done builing 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..65b6ab2acc88 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" diff --git a/docs/env.yml b/docs/env.yml index c7f47238a4c4..e6a8279b521d 100644 --- a/docs/env.yml +++ b/docs/env.yml @@ -3,5 +3,13 @@ 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<2.0" + - r-rmarkdown=2.11 + - r-roxygen2=7.1.2 - sphinx - "sphinx_rtd_theme>=0.5" From 54b608d89ebad2e63017097fa5370a6de3457650 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Mon, 17 Jan 2022 21:23:17 -0600 Subject: [PATCH 03/18] simplify build script and add docs flag to gitignore --- .gitignore | 1 + docs/README.rst | 6 +++--- docs/build-docs.sh | 8 +++----- docs/env.yml | 2 +- 4 files changed, 8 insertions(+), 9 deletions(-) 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/docs/README.rst b/docs/README.rst index b60081ba6f26..8dd3b31722df 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -13,7 +13,7 @@ After each commit on ``master``, documentation is updated and published to `Read Build ----- -It is not necessary to re-build this documentatioon while modifying LightGBM's source code. +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. @@ -28,6 +28,7 @@ Run the following from the root of this repository to pull the relevant image an docker run \ --rm \ + --user=0 \ -v $(pwd):/opt/LightGBM \ --env C_API=true \ --env CONDA=/opt/conda \ @@ -35,9 +36,8 @@ Run the following from the root of this repository to pull the relevant image an --env READTHEDOCS=true \ --workdir=/opt/LightGBM/docs \ --entrypoint="" \ - --user=0 \ -it readthedocs/build:ubuntu-20.04-2021.09.23 \ - /bin/bash --noprofile --norc build-docs.sh + /bin/bash build-docs.sh When that code completes, open ``docs/html/index.html`` in your browser. diff --git a/docs/build-docs.sh b/docs/build-docs.sh index 0080252e03aa..fce657259940 100644 --- a/docs/build-docs.sh +++ b/docs/build-docs.sh @@ -1,7 +1,5 @@ #!/bin/bash -set -e -u -o pipefail - rm -f ./_FIRST_RUN.flag ARCH=$(uname -m) @@ -12,13 +10,13 @@ curl \ -o ${HOME}/conda.sh \ "https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-${ARCH}.sh" -bash ${HOME}/conda.sh -b -p ${CONDA} +/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 + --file env.yml || exit -1 source activate docs-env @@ -33,4 +31,4 @@ ${CONDA}/envs/docs-env/bin/python \ -D language=en \ . _build/html -echo "Done builing docs. Open docs/_build/html/index.html in a web browser to view them." +echo "Done building docs. Open docs/_build/html/index.html in a web browser to view them." diff --git a/docs/env.yml b/docs/env.yml index e6a8279b521d..b2d37dd5fc28 100644 --- a/docs/env.yml +++ b/docs/env.yml @@ -8,7 +8,7 @@ dependencies: - r-jsonlite=1.7.2 - r-knitr=1.37 - r-matrix=1.4_0 - - "r-pkgdown<2.0" + - r-pkgdown=1.6.1 - r-rmarkdown=2.11 - r-roxygen2=7.1.2 - sphinx From 5dd9c8ec846475db67d2026332a78c3fbf5c6268 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Mon, 17 Jan 2022 21:26:44 -0600 Subject: [PATCH 04/18] exit with non-0 if build fails --- docs/build-docs.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build-docs.sh b/docs/build-docs.sh index fce657259940..53a4501179e6 100644 --- a/docs/build-docs.sh +++ b/docs/build-docs.sh @@ -29,6 +29,6 @@ ${CONDA}/envs/docs-env/bin/python \ -b html \ -d _build/doctrees \ -D language=en \ - . _build/html + . _build/html || exit -1 echo "Done building docs. Open docs/_build/html/index.html in a web browser to view them." From 8df9337e2c5b99e893b045f06afa361e58f0fc96 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Mon, 17 Jan 2022 21:37:19 -0600 Subject: [PATCH 05/18] update CI job --- .ci/test.sh | 20 +++++++++++++++----- docs/conf.py | 2 ++ docs/env.yml | 2 ++ docs/requirements.txt | 2 -- docs/requirements_base.txt | 2 -- 5 files changed, 19 insertions(+), 9 deletions(-) delete mode 100644 docs/requirements.txt delete mode 100644 docs/requirements_base.txt diff --git a/.ci/test.sh b/.ci/test.sh index e3d385ab8b71..786321b202dc 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -29,15 +29,22 @@ 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 \ + 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 +67,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 \ diff --git a/docs/conf.py b/docs/conf.py index 65b6ab2acc88..ce13e6801ae6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -283,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 @@ -296,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 index b2d37dd5fc28..c34675af5b36 100644 --- a/docs/env.yml +++ b/docs/env.yml @@ -1,4 +1,6 @@ name: docs-env +channels: + - conda-forge dependencies: - breathe - python=3.9 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 From 57a053770a44f9342d9b0342dba9a259b2f64108 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Mon, 17 Jan 2022 22:20:10 -0600 Subject: [PATCH 06/18] add doxygen --- .ci/test.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/.ci/test.sh b/.ci/test.sh index 786321b202dc..45a7d138be30 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -43,6 +43,7 @@ if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then -n docs-env \ -c conda-forge \ --override-channels \ + doxygen \ rstcheck source activate docs-env # check reStructuredText formatting From d53e14e993aff2946e32483291de66afaced32d3 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Tue, 18 Jan 2022 18:49:01 -0600 Subject: [PATCH 07/18] remove outdated requirement_base.txt reference --- docs/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.rst b/docs/README.rst index 8dd3b31722df..688439eb6372 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -62,6 +62,6 @@ If you faced any problems with Doxygen installation or you simply do not need do .. code:: sh - pip install -r requirements_base.txt + pip install breathe sphinx 'sphinx_rtd_theme>0.5' export C_API=NO || set C_API=NO make html From e9aa5a1030e5cd406a8d2b0d4e042b5f9c41f601 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Tue, 18 Jan 2022 22:13:40 -0600 Subject: [PATCH 08/18] use conda create instead of conda env create --- .ci/test.sh | 5 ++++- docs/build-docs.sh | 3 ++- docs/env.yml | 1 - 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/.ci/test.sh b/.ci/test.sh index 45a7d138be30..a86cd35be0de 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -33,9 +33,12 @@ cd $BUILD_DIRECTORY if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then cd $BUILD_DIRECTORY/docs - conda env create \ + conda create \ -q \ + -y \ -n docs-env \ + -c conda-forge \ + --override-channels \ -f ./env.yml conda install \ -q \ diff --git a/docs/build-docs.sh b/docs/build-docs.sh index 53a4501179e6..14ac3e168190 100644 --- a/docs/build-docs.sh +++ b/docs/build-docs.sh @@ -14,7 +14,8 @@ curl \ conda config --set always_yes yes --set changeps1 no -mamba env create \ +mamba create \ + --yes \ --name docs-env \ --file env.yml || exit -1 diff --git a/docs/env.yml b/docs/env.yml index c34675af5b36..68179d8ccf5e 100644 --- a/docs/env.yml +++ b/docs/env.yml @@ -4,7 +4,6 @@ channels: dependencies: - breathe - python=3.9 - - pip - r-base=4.1.2 - r-data.table=1.14.2 - r-jsonlite=1.7.2 From 343932f34ac4005629c7925936a5c7e19811c4ad Mon Sep 17 00:00:00 2001 From: James Lamb Date: Tue, 18 Jan 2022 22:31:32 -0600 Subject: [PATCH 09/18] fix conda create flags --- .ci/test.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.ci/test.sh b/.ci/test.sh index a86cd35be0de..2af1e677db40 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -39,7 +39,7 @@ if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then -n docs-env \ -c conda-forge \ --override-channels \ - -f ./env.yml + --file ./env.yml || exit -1 conda install \ -q \ -y \ @@ -47,7 +47,7 @@ if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then -c conda-forge \ --override-channels \ doxygen \ - rstcheck + rstcheck || exit -1 source activate docs-env # check reStructuredText formatting cd $BUILD_DIRECTORY/python-package From 8b90bbf7f519b33db5c574f8b251d283de6ffc14 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Tue, 18 Jan 2022 22:49:13 -0600 Subject: [PATCH 10/18] add nodefaults to env.yml --- .ci/test.sh | 6 +----- docs/env.yml | 1 + 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/.ci/test.sh b/.ci/test.sh index 2af1e677db40..059818c872dd 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -33,12 +33,8 @@ cd $BUILD_DIRECTORY if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then cd $BUILD_DIRECTORY/docs - conda create \ - -q \ - -y \ + conda env create \ -n docs-env \ - -c conda-forge \ - --override-channels \ --file ./env.yml || exit -1 conda install \ -q \ diff --git a/docs/env.yml b/docs/env.yml index 68179d8ccf5e..e55f053d9dad 100644 --- a/docs/env.yml +++ b/docs/env.yml @@ -1,6 +1,7 @@ name: docs-env channels: - conda-forge + - nodefaults dependencies: - breathe - python=3.9 From fef18e6be9291c909d6de41058a4956563cb2b76 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Wed, 19 Jan 2022 22:48:30 -0600 Subject: [PATCH 11/18] Update docs/README.rst Co-authored-by: Nikita Titov --- docs/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.rst b/docs/README.rst index 688439eb6372..e3196179058c 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -62,6 +62,6 @@ If you faced any problems with Doxygen installation or you simply do not need do .. code:: sh - pip install breathe sphinx 'sphinx_rtd_theme>0.5' + pip install sphinx 'sphinx_rtd_theme>0.5' export C_API=NO || set C_API=NO make html From 0c312eef03d1600853d4e35f8198ee79b6514cb0 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Wed, 19 Jan 2022 23:32:50 -0600 Subject: [PATCH 12/18] try to fix check-docs CI job --- .ci/test.sh | 13 ++++++++++++- docs/build-docs.sh | 2 +- docs/env.yml | 2 +- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/.ci/test.sh b/.ci/test.sh index 059818c872dd..5b69bf830740 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -33,7 +33,18 @@ cd $BUILD_DIRECTORY if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then cd $BUILD_DIRECTORY/docs - conda env create \ + conda create \ + -q \ + -y \ + -c conda-forge \ + --override-channels \ + -n docs-env \ + python=3.9 + conda install \ + -q \ + -y \ + -c conda-forge \ + --override-channels \ -n docs-env \ --file ./env.yml || exit -1 conda install \ diff --git a/docs/build-docs.sh b/docs/build-docs.sh index 14ac3e168190..e90e15651678 100644 --- a/docs/build-docs.sh +++ b/docs/build-docs.sh @@ -21,7 +21,7 @@ mamba create \ source activate docs-env -${CONDA}/envs/docs-env/bin/python \ +python \ -m sphinx \ -T \ -E \ diff --git a/docs/env.yml b/docs/env.yml index e55f053d9dad..a5b1b80e4f69 100644 --- a/docs/env.yml +++ b/docs/env.yml @@ -1,7 +1,7 @@ name: docs-env channels: - - conda-forge - nodefaults + - conda-forge dependencies: - breathe - python=3.9 From 3efc6195faf4936cbfe8a6a32b3adc2a2c6e2ece Mon Sep 17 00:00:00 2001 From: James Lamb Date: Wed, 19 Jan 2022 23:35:01 -0600 Subject: [PATCH 13/18] additional changes --- .ci/test.sh | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.ci/test.sh b/.ci/test.sh index 5b69bf830740..582814a4b8c4 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -40,11 +40,7 @@ if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then --override-channels \ -n docs-env \ python=3.9 - conda install \ - -q \ - -y \ - -c conda-forge \ - --override-channels \ + conda env update \ -n docs-env \ --file ./env.yml || exit -1 conda install \ From e88ba3805903f220f9f75ec9200a3aa46774683b Mon Sep 17 00:00:00 2001 From: James Lamb Date: Sun, 13 Feb 2022 21:21:29 -0600 Subject: [PATCH 14/18] switch from mamba to miniforge --- .ci/test.sh | 18 +++++------------- .readthedocs.yaml | 2 +- docs/build-docs.sh | 19 ++++--------------- 3 files changed, 10 insertions(+), 29 deletions(-) diff --git a/.ci/test.sh b/.ci/test.sh index 2b8f743f213c..74bce60190d5 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -29,29 +29,24 @@ 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 create \ - -q \ - -y \ - -c conda-forge \ - --override-channels \ - -n docs-env \ - python=3.9 conda env update \ - -n docs-env \ + -n $CONDA_ENV \ --file ./env.yml || exit -1 conda install \ -q \ -y \ - -n docs-env \ + -n $CONDA_ENV \ -c conda-forge \ --override-channels \ doxygen \ rstcheck || exit -1 - source activate docs-env # check reStructuredText formatting cd $BUILD_DIRECTORY/python-package rstcheck --report warning $(find . -type f -name "*.rst") || exit -1 @@ -74,9 +69,6 @@ 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 \ cmakelint \ diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 0e116213080c..7d63476a0f79 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -2,7 +2,7 @@ version: 2 build: os: "ubuntu-20.04" tools: - python: "mambaforge-4.10" + python: "miniconda3-4.7" conda: environment: docs/env.yml formats: diff --git a/docs/build-docs.sh b/docs/build-docs.sh index e90e15651678..5662fa046995 100644 --- a/docs/build-docs.sh +++ b/docs/build-docs.sh @@ -2,15 +2,14 @@ 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" + -o ${HOME}/miniforge.sh \ + "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-x86_64.sh" -/bin/bash ${HOME}/conda.sh -b -p ${CONDA} +/bin/bash ${HOME}/miniforge.sh -b -p ${CONDA} conda config --set always_yes yes --set changeps1 no @@ -20,16 +19,6 @@ mamba create \ --file env.yml || exit -1 source activate docs-env - -python \ - -m sphinx \ - -T \ - -E \ - -W \ - --keep-going \ - -b html \ - -d _build/doctrees \ - -D language=en \ - . _build/html || exit -1 +make clean html || exit -1 echo "Done building docs. Open docs/_build/html/index.html in a web browser to view them." From ac037b54dac03b1ab3164cd0277eacbf3e2ad59f Mon Sep 17 00:00:00 2001 From: James Lamb Date: Tue, 15 Feb 2022 21:51:39 -0600 Subject: [PATCH 15/18] simplify docker command and fix issues in local build script --- docs/README.rst | 3 +-- docs/build-docs.sh | 5 ++--- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index e3196179058c..f732c1d9bb4c 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -31,8 +31,7 @@ Run the following from the root of this repository to pull the relevant image an --user=0 \ -v $(pwd):/opt/LightGBM \ --env C_API=true \ - --env CONDA=/opt/conda \ - --env PYTHONUNBUFFERED=1 \ + --env CONDA=/opt/miniforge \ --env READTHEDOCS=true \ --workdir=/opt/LightGBM/docs \ --entrypoint="" \ diff --git a/docs/build-docs.sh b/docs/build-docs.sh index 5662fa046995..761294230826 100644 --- a/docs/build-docs.sh +++ b/docs/build-docs.sh @@ -7,14 +7,13 @@ export PATH="${CONDA}/bin:${PATH}" curl \ -L \ -o ${HOME}/miniforge.sh \ - "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-x86_64.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 -mamba create \ - --yes \ +conda env create \ --name docs-env \ --file env.yml || exit -1 From 8010f99fda097fa9702b9c900f31d5d078eaf1fc Mon Sep 17 00:00:00 2001 From: James Lamb Date: Wed, 16 Feb 2022 19:31:56 -0600 Subject: [PATCH 16/18] Apply suggestions from code review Co-authored-by: Nikita Titov --- .ci/test.sh | 2 -- docs/README.rst | 6 +++--- docs/build-docs.sh | 2 +- 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/.ci/test.sh b/.ci/test.sh index 74bce60190d5..9e6bf0085ea2 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -43,8 +43,6 @@ if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then -q \ -y \ -n $CONDA_ENV \ - -c conda-forge \ - --override-channels \ doxygen \ rstcheck || exit -1 # check reStructuredText formatting diff --git a/docs/README.rst b/docs/README.rst index f732c1d9bb4c..40666c34372a 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -20,7 +20,7 @@ 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 `_. +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. @@ -51,7 +51,7 @@ You can build the documentation locally. Just install Doxygen and run in ``docs` .. code:: sh - pip install breathe sphinx 'sphinx_rtd_theme>0.5' + 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. @@ -61,6 +61,6 @@ If you faced any problems with Doxygen installation or you simply do not need do .. code:: sh - pip install sphinx 'sphinx_rtd_theme>0.5' + 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 index 761294230826..10d7b7aedc5d 100644 --- a/docs/build-docs.sh +++ b/docs/build-docs.sh @@ -5,7 +5,7 @@ rm -f ./_FIRST_RUN.flag export PATH="${CONDA}/bin:${PATH}" curl \ - -L \ + -sL \ -o ${HOME}/miniforge.sh \ https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh From 5faaa44b26fbd0a1fe7827ab5760715c06d493f8 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Wed, 16 Feb 2022 19:35:24 -0600 Subject: [PATCH 17/18] update docs and conda --- docs/README.rst | 11 ++++++----- docs/build-docs.sh | 1 + 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index 40666c34372a..25b523434cee 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -42,19 +42,20 @@ 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. + 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. -Locally -^^^^^^^ +Without Docker +^^^^^^^^^^^^^^ -You can build the documentation locally. Just install Doxygen and run in ``docs`` folder +You can build the documentation locally without Docker. Just install Doxygen and run in ``docs`` folder .. code:: sh 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. +To build the R docuumentation locally, use the Docker-based approach described above. Consider using common R utilities for documentation generation, if you need it. 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: diff --git a/docs/build-docs.sh b/docs/build-docs.sh index 10d7b7aedc5d..689a30df9962 100644 --- a/docs/build-docs.sh +++ b/docs/build-docs.sh @@ -12,6 +12,7 @@ curl \ /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 \ From 3e66b3f5d441b37b94f150ad5c9eb2bcbd43e3a3 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Thu, 17 Feb 2022 19:59:03 -0600 Subject: [PATCH 18/18] Apply suggestions from code review Co-authored-by: Nikita Titov --- docs/README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index 25b523434cee..7ce36aed1d95 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -38,7 +38,7 @@ Run the following from the root of this repository to pull the relevant image an -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. +When that code completes, open ``docs/_build/html/index.html`` in your browser. .. note:: @@ -55,8 +55,8 @@ You can build the documentation locally without Docker. Just install Doxygen and make html Note that this will not build the R documentation. -To build the R docuumentation locally, use the Docker-based approach described above. 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: