diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index d3ebbbd96b48..584af0987e92 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -13,12 +13,25 @@ jobs: - runs-on=${{ github.run_id }} - runner=linux-amd64-cpu - tag=doc-build-jvm-docs + steps: # Restart Docker daemon so that it recognizes the ephemeral disks - run: sudo systemctl restart docker - uses: actions/checkout@v4 with: submodules: "true" + + - name: Get the git hash for the push event. + if: ${{ github.event_name == 'push' }} + shell: bash + run: | + echo "HEAD_SHA=${GITHUB_SHA}" >> ${GITHUB_ENV} + - name: Get the git hash for the PR event. + if: ${{ github.event_name == 'pull_request' }} + shell: bash + run: | + echo "HEAD_SHA=${{ github.event.pull_request.head.sha }}" >> ${GITHUB_ENV} + - name: Log into Docker registry (AWS ECR) run: bash ops/pipeline/login-docker-registry.sh - run: bash ops/pipeline/build-jvm-gpu.sh @@ -29,9 +42,43 @@ jobs: # branch can be the name of the dmlc/xgboost branch, or `PR-{number}`. python3 ops/pipeline/manage-artifacts.py upload \ --s3-bucket xgboost-docs \ - --prefix ${BRANCH_NAME}/${GITHUB_SHA} --make-public \ + --prefix ${BRANCH_NAME}/${{ env.HEAD_SHA }} --make-public \ jvm-packages/${{ env.BRANCH_NAME }}.tar.bz2 + build-r-docs: + name: Build docs for the R package + runs-on: + - runs-on=${{ github.run_id }} + - runner=linux-amd64-cpu + - tag=r-tests-build-docs + steps: + # Restart Docker daemon so that it recognizes the ephemeral disks + - run: sudo systemctl restart docker + - uses: actions/checkout@v4 + with: + submodules: "true" + + - name: Get the git hash for the push event. + if: ${{ github.event_name == 'push' }} + shell: bash + run: | + echo "HEAD_SHA=${GITHUB_SHA}" >> ${GITHUB_ENV} + - name: Get the git hash for the PR event. + if: ${{ github.event_name == 'pull_request' }} + shell: bash + run: | + echo "HEAD_SHA=${{ github.event.pull_request.head.sha }}" >> ${GITHUB_ENV} + + - name: Log into Docker registry (AWS ECR) + run: bash ops/pipeline/login-docker-registry.sh + - run: bash ops/pipeline/build-r-docs.sh + - name: Upload R doc + run: | + python3 ops/pipeline/manage-artifacts.py upload \ + --s3-bucket xgboost-docs \ + --prefix ${BRANCH_NAME}/${{ env.HEAD_SHA }} --make-public \ + r-docs-${{ env.BRANCH_NAME }}.tar.bz2 + trigger-rtd-build: needs: [build-jvm-docs] name: Trigger Read The Docs build. diff --git a/.github/workflows/jvm_tests.yml b/.github/workflows/jvm_tests.yml index fc2f21d68043..a1b170c9d105 100644 --- a/.github/workflows/jvm_tests.yml +++ b/.github/workflows/jvm_tests.yml @@ -95,36 +95,6 @@ jobs: AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID_IAM_S3_UPLOADER }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY_IAM_S3_UPLOADER }} - build-jvm-docs: - name: Build docs for JVM packages - needs: [build-jvm-gpu] - runs-on: - - runs-on=${{ github.run_id }} - - runner=linux-amd64-cpu - - tag=jvm-tests-build-jvm-docs - steps: - # Restart Docker daemon so that it recognizes the ephemeral disks - - run: sudo systemctl restart docker - - uses: actions/checkout@v4 - with: - submodules: "true" - - name: Log into Docker registry (AWS ECR) - run: bash ops/pipeline/login-docker-registry.sh - - name: Unstash files - run: | - python3 ops/pipeline/manage-artifacts.py download \ - --s3-bucket ${{ env.RUNS_ON_S3_BUCKET_CACHE }} \ - --prefix cache/${{ github.run_id }}/build-jvm-gpu \ - --dest-dir lib \ - libxgboost4j.so - - run: bash ops/pipeline/build-jvm-doc.sh - - name: Upload JVM doc - run: | - python3 ops/pipeline/manage-artifacts.py upload \ - --s3-bucket xgboost-docs \ - --prefix ${BRANCH_NAME}/${GITHUB_SHA} --make-public \ - jvm-packages/${{ env.BRANCH_NAME }}.tar.bz2 - build-test-jvm-packages: name: Build and test JVM packages (Linux, Scala ${{ matrix.scala_version }}) runs-on: diff --git a/R-package/.Rbuildignore b/R-package/.Rbuildignore index b1932e324589..ca9c76e2411a 100644 --- a/R-package/.Rbuildignore +++ b/R-package/.Rbuildignore @@ -6,3 +6,6 @@ README.md ^doc$ ^Meta$ +^_pkgdown\.yml$ +^docs$ +^pkgdown$ diff --git a/R-package/.gitignore b/R-package/.gitignore new file mode 100644 index 000000000000..d8f8d46921aa --- /dev/null +++ b/R-package/.gitignore @@ -0,0 +1 @@ +docs diff --git a/R-package/README.md b/R-package/README.md index f68b1954be7d..68a3ffbbf021 100644 --- a/R-package/README.md +++ b/R-package/README.md @@ -1,13 +1,13 @@ -XGBoost R Package for Scalable GBM -================================== +XGBoost R Package +================= [![CRAN Status Badge](http://www.r-pkg.org/badges/version/xgboost)](https://cran.r-project.org/web/packages/xgboost) [![CRAN Downloads](http://cranlogs.r-pkg.org/badges/xgboost)](https://cran.rstudio.com/web/packages/xgboost/index.html) -[![Documentation Status](https://readthedocs.org/projects/xgboost/badge/?version=latest)](http://xgboost.readthedocs.org/en/latest/R-package/index.html) +[![Documentation Status](https://readthedocs.org/projects/xgboost/badge/?version=latest)](https://xgboost.readthedocs.org/en/latest/R-package/index.html) Resources --------- -* [XGBoost R Package Online Documentation](http://xgboost.readthedocs.org/en/latest/R-package/index.html) +* [XGBoost R Package Online Documentation](https://xgboost.readthedocs.org/en/stable/R-package/index.html) - Check this out for detailed documents, examples and tutorials. Installation @@ -19,13 +19,7 @@ We are [on CRAN](https://cran.r-project.org/web/packages/xgboost/index.html) now install.packages('xgboost') ``` -For more detailed installation instructions, please see [here](http://xgboost.readthedocs.org/en/latest/build.html#r-package-installation). - -Examples --------- - -* Please visit [walk through example](demo). -* See also the [example scripts](../demo/kaggle-higgs) for Kaggle Higgs Challenge, including [speedtest script](../demo/kaggle-higgs/speedtest.R) on this dataset and the one related to [Otto challenge](../demo/kaggle-otto), including a [RMarkdown documentation](../demo/kaggle-otto/understandingXGBoostModel.Rmd). +For more detailed installation instructions, please see [here](https://xgboost.readthedocs.io/en/stable/install.html). Development ----------- diff --git a/R-package/pkgdown/_pkgdown.yml b/R-package/pkgdown/_pkgdown.yml new file mode 100644 index 000000000000..c92f3ac70067 --- /dev/null +++ b/R-package/pkgdown/_pkgdown.yml @@ -0,0 +1,92 @@ +url: https://github.com/dmlc/xgboost + +template: + bootstrap: 5 + math-rendering: mathjax + +reference: + - title: High Level Interface + desc: High level XGBoost interface + contents: + - "xgboost" + - "predict.xgboost" + - "print.xgboost" + - title: Datasets + desc: Test datasets bundled with the R package. + contents: + - "agaricus.train" + - "agaricus.test" + - title: Global Configuration + desc: Global configuration for the XGBoost library. + contents: + - "xgb.config" + - "xgb.set.config" + - "xgb.get.config" + - title: DMatrix + desc: Low-level data storage. + contents: + - "xgb.DMatrix" + - "xgb.DMatrix.hasinfo" + - "xgb.DMatrix.save" + - "dim.xgb.DMatrix" + - "dimnames.xgb.DMatrix" + - "print.xgb.DMatrix" + - "xgb.DataBatch" + - "xgb.DataIter" + - "xgb.get.DMatrix.data" + - "xgb.get.DMatrix.num.non.missing" + - "xgb.ExtMemDMatrix" + - "xgb.QuantileDMatrix.from_iterator" + - "xgb.get.DMatrix.qcut" + - "xgb.slice.DMatrix" + - title: Booster + desc: The model for XGBoost. + contents: + - "a-compatibility-note-for-saveRDS-save" + - "coef.xgb.Booster" + - "getinfo.xgb.Booster" + - "predict.xgb.Booster" + - "print.xgb.Booster" + - "xgb.load" + - "xgb.load.raw" + - "xgb.save" + - "xgb.save.raw" + - "xgb.copy.Booster" + - "xgb.slice.Booster" + - "xgb.get.num.boosted.rounds" + - "xgb.is.same.Booster" + - "xgb.importance" + - "xgb.attr" + - "xgb.create.features" + - "xgb.model.dt.tree" + - "xgb.model.parameters<-" + - "xgb.ggplot.deepness" + - "xgb.dump" + - "variable.names.xgb.Booster" + - "xgb.ggplot.importance" + - "xgb.plot.multi.trees" + - "xgb.plot.shap" + - "xgb.ggplot.shap.summary" + - "xgb.plot.tree" + - "xgb.gblinear.history" + - title: Training Callbacks + desc: Callback functions used for training. + contents: + - "xgb.Callback" + - "xgb.cb.cv.predict" + - "xgb.cb.early.stop" + - "xgb.cb.evaluation.log" + - "xgb.cb.gblinear.history" + - "xgb.cb.print.evaluation" + - "xgb.cb.reset.parameters" + - "xgb.cb.save.model" + - title: Low-level Training Functions + desc: Low-level Training Functions with DMatrix and Booster + contents: + - "xgb.params" + - "xgb.train" + - "xgb.cv" + - "print.xgb.cv.synchronous" + - title: Deprecation Settings + contents: + - "xgboost-options" diff --git a/R-package/tests/helper_scripts/install_deps.R b/R-package/tests/helper_scripts/install_deps.R index 757475541fd4..8bb56b76a576 100644 --- a/R-package/tests/helper_scripts/install_deps.R +++ b/R-package/tests/helper_scripts/install_deps.R @@ -26,7 +26,6 @@ pkgs <- c( "RhpcBLASctl", ## imports "Matrix", - "methods", "data.table", "jsonlite" ) diff --git a/R-package/vignettes/xgboost_introduction.Rmd b/R-package/vignettes/xgboost_introduction.Rmd index 8d3573f11f5f..6a08dd29eaec 100644 --- a/R-package/vignettes/xgboost_introduction.Rmd +++ b/R-package/vignettes/xgboost_introduction.Rmd @@ -12,7 +12,10 @@ output: toc_float: true --- -# Introduction +XGBoost for R introduction +========================== + +## Introduction **XGBoost** is an optimized distributed gradient boosting library designed to be highly **efficient**, **flexible** and **portable**. It implements machine learning algorithms under the [Gradient Boosting](https://en.wikipedia.org/wiki/Gradient_boosting) framework. XGBoost provides a parallel tree boosting (also known as GBDT, GBM) that solve many data science problems in a fast and accurate way. The same code runs on major distributed environment (Hadoop, SGE, MPI) and can solve problems beyond billions of examples. @@ -22,7 +25,7 @@ For more details about XGBoost's features and usage, see the [online documentati This short vignette outlines the basic usage of the R interface for XGBoost, assuming the reader has some familiarity with the underlying concepts behind statistical modeling with gradient-boosted decision trees. -# Building a predictive model +## Building a predictive model At its core, XGBoost consists of a C++ library which offers bindings for different programming languages, including R. The R package for XGBoost provides an idiomatic interface similar to those of other statistical modeling packages using and x/y design, as well as a lower-level interface that interacts more directly with the underlying core library and which is similar to those of other language bindings like Python, plus various helpers to interact with its model objects such as by plotting their feature importances or converting them to other formats. @@ -62,7 +65,7 @@ model_abserr <- xgboost(x, y, objective = "reg:absoluteerror", nthreads = 1, nro _Note: the objective must match with the type of the "y" response variable - for example, classification objectives for discrete choices require "factor" types, while regression models for real-valued data require "numeric" types._ -# Model parameters +## Model parameters XGBoost models allow a large degree of control over how they are built. By their nature, gradient-boosted decision tree ensembles are able to capture very complex patterns between features in the data and a response variable, which also means they can suffer from overfitting if not controlled appropirately. @@ -105,7 +108,7 @@ xgboost( ) ``` -# Examining model objects +## Examining model objects XGBoost model objects for the most part consist of a pointer to a C++ object where most of the information is held and which is interfaced through the utility functions and methods in the package, but also contains some R attributes that can be retrieved (and new ones added) through `attributes()`: @@ -131,7 +134,7 @@ xgb.importance(model) xgb.model.dt.tree(model) ``` -# Other features +## Other features XGBoost supports many additional features on top of its traditional gradient-boosting framework, including, among others: @@ -143,7 +146,7 @@ XGBoost supports many additional features on top of its traditional gradient-boo See the [online documentation](https://xgboost.readthedocs.io/en/stable/index.html) - particularly the [tutorials section](https://xgboost.readthedocs.io/en/stable/tutorials/index.html) - for a glimpse over further functionalities that XGBoost offers. -# The low-level interface +## The low-level interface In addition to the `xgboost(x, y, ...)` function, XGBoost also provides a lower-level interface for creating model objects through the function `xgb.train()`, which resembles the same `xgb.train` functions in other language bindings of XGBoost. diff --git a/doc/R-package/.gitignore b/doc/R-package/.gitignore index b25c15b81fae..8a51ab19c717 100644 --- a/doc/R-package/.gitignore +++ b/doc/R-package/.gitignore @@ -1 +1,2 @@ *~ +*.md diff --git a/doc/R-package/Makefile b/doc/R-package/Makefile index c9a3a494404e..5eff72863f43 100644 --- a/doc/R-package/Makefile +++ b/doc/R-package/Makefile @@ -5,6 +5,8 @@ PKGROOT=../../R-package xgboostfromJSON.md: $(PKGROOT)/vignettes/xgboostfromJSON.Rmd xgboost_introduction.md: $(PKGROOT)/vignettes/xgboost_introduction.Rmd +all: xgboostfromJSON.md xgboost_introduction.md + # General Rules for build rmarkdowns, need knitr %.md: Rscript -e \ diff --git a/doc/R-package/index.rst b/doc/R-package/index.rst index a40e1d4d734c..30b6f83e5232 100644 --- a/doc/R-package/index.rst +++ b/doc/R-package/index.rst @@ -9,19 +9,32 @@ XGBoost R Package You have found the XGBoost R Package! +.. toctree:: + :maxdepth: 2 + :titlesonly: + *********** Get Started *********** + * Checkout the :doc:`Installation Guide ` contains instructions to install xgboost, and :doc:`Tutorials ` for examples on how to use XGBoost for various tasks. -* Read the `API documentation `_. +* Read the latest `API documentation <../r_docs/R-package/docs/reference/index.html>`__ . This might refer to a newer version than the one on CRAN. +* Read the `CRAN documentation `_. + +********* +Vignettes +********* + +.. toctree:: + + xgboost_introduction + xgboostfromJSON ************ Other topics ************ .. toctree:: - :maxdepth: 2 - :titlesonly: Migrating code from previous XGBoost versions Handling of indexable elements diff --git a/doc/R-package/r_docs/index.rst b/doc/R-package/r_docs/index.rst new file mode 100644 index 000000000000..88a8b72879e2 --- /dev/null +++ b/doc/R-package/r_docs/index.rst @@ -0,0 +1,5 @@ +:orphan: + +============= +XGBoost R API +============= diff --git a/doc/conf.py b/doc/conf.py index 52b99e5380ee..ce6a0219ccb1 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -108,8 +108,9 @@ def get_sha(branch: str) -> str | None: return res.stdout.decode("utf-8").strip() -def build_jvm_docs() -> None: +def download_jvm_docs() -> None: """Fetch docs for the JVM packages""" + print("Download JVM documents from S3.") branch = get_branch() commit = get_sha(branch) if commit is None: @@ -130,12 +131,10 @@ def try_fetch_jvm_doc(branch: str) -> bool: filename, _ = urllib.request.urlretrieve(url) print(f"Finished: {url} -> {filename}") if not os.path.exists(TMP_DIR): - print(f"Create directory {TMP_DIR}") os.mkdir(TMP_DIR) jvm_doc_dir = os.path.join(TMP_DIR, "jvm_docs") if os.path.exists(jvm_doc_dir): shutil.rmtree(jvm_doc_dir) - print(f"Create directory {jvm_doc_dir}") os.mkdir(jvm_doc_dir) with tarfile.open(filename, "r:bz2") as t: @@ -150,6 +149,52 @@ def try_fetch_jvm_doc(branch: str) -> bool: try_fetch_jvm_doc("master") +def download_r_docs() -> None: + """Fetch R document from s3.""" + branch = get_branch() + commit = get_sha(branch) + print("Download R documents from S3.") + if commit is None: + print("Couldn't find commit to build R docs.") + return + + def try_fetch_r_doc(branch: str) -> bool: + try: + local_r_docs = os.environ.get("XGBOOST_R_DOCS", None) + if local_r_docs is not None: + filename = os.path.expanduser(local_r_docs) + else: + url = f"{S3_BUCKET}/{branch}/{commit}/r-docs-{branch}.tar.bz2" + filename, _ = urllib.request.urlretrieve(url) + print(f"Finished: {url} -> {filename}") + + if not os.path.exists(TMP_DIR): + os.mkdir(TMP_DIR) + r_doc_dir = os.path.join(TMP_DIR, "r_docs") + if os.path.exists(r_doc_dir): + shutil.rmtree(r_doc_dir) + os.mkdir(r_doc_dir) + + with tarfile.open(filename, "r:bz2") as t: + t.extractall(r_doc_dir) + + for root, subdir, files in os.walk( + os.path.join(r_doc_dir, "doc", "R-package") + ): + for f in files: + assert f.endswith(".md") + src = os.path.join(root, f) + dst = os.path.join(PROJECT_ROOT, "doc", "R-package", f) + shutil.move(src, dst) + return True + except HTTPError: + print(f"R doc not found at {url}. Falling back to the master branch.") + return False + + if not try_fetch_r_doc(branch): + try_fetch_r_doc("master") + + def is_readthedocs_build(): if os.environ.get("READTHEDOCS", None) == "True": return True @@ -164,7 +209,8 @@ def is_readthedocs_build(): if is_readthedocs_build(): run_doxygen() - build_jvm_docs() + download_jvm_docs() + download_r_docs() # If extensions (or modules to document with autodoc) are in another directory, diff --git a/doc/contrib/docs.rst b/doc/contrib/docs.rst index df2b2692a28a..b0ef7d0a5fca 100644 --- a/doc/contrib/docs.rst +++ b/doc/contrib/docs.rst @@ -81,6 +81,40 @@ Build the Python Docs using pip and Conda Build finished. The HTML pages are in _build/html. +************* +Read The Docs +************* + +`Read the Docs `__ (RTD for short) is an online document hosting +service and hosts the `XGBoost document site +`__. The document builder used by RTD is +relatively lightweight. However some of the packages like the R binding require a compiled +XGBoost along with all the optional dependencies to render the document. As a result, both +jvm-based packages and the R package's document is built with an independent CI pipeline +and fetched during online document build. + +The sphinx configuration file ``xgboost/doc/conf.py`` acts as the fetcher. During build, +the fetched artifacts are stored in ``xgboost/doc/tmp/jvm_docs`` and +``xgboost/doc/tmp/r_docs`` respectively. For the R package, there's a dummy index file in +``xgboost/doc/R-package/r_docs`` . Jvm doc is similar. As for the C doc, it's generated +using doxygen and processed by breathe during build as it's relatively cheap. The +generated xml files are stored in ``xgboost/doc/tmp/dev`` . + +The ``xgboost/doc/tmp`` is part of the ``html_extra_path`` sphinx configuration specified +in the ``conf.py`` file, which informs sphinx to copy the extracted html files to the +build directory. Following is a list of environment variables used by the fetchers in +``conf.py``: + + - ``READTHEDOCS``: Read the docs flag. Build the full documentation site including R, JVM and + C doc when set to ``True`` (case sensitive). + - ``XGBOOST_R_DOCS``: Local path for pre-built R document, used for development. + - ``XGBOOST_JVM_DOCS``: Local path for pre-built JVM document, used for development. + +As of writing, RTD doesn't provide any facility to be embedded as a GitHub action but we +need a way to specify the dependency between the CI pipelines and the document build in +order to fetch the correct artifact. The workaround is to use an extra GA step to notify +RTD using its `REST API `__. + ******** Examples ******** diff --git a/doc/index.rst b/doc/index.rst index ca9677552da2..6f37aa464eca 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -20,7 +20,6 @@ Contents get_started tutorials/index faq - XGBoost User Forum GPU Support parameter prediction diff --git a/doc/jvm/javadocs/index.rst b/doc/jvm/javadocs/index.rst index 33bf528129e4..c6e38af94eca 100644 --- a/doc/jvm/javadocs/index.rst +++ b/doc/jvm/javadocs/index.rst @@ -1,3 +1,5 @@ +:orphan: + ================== XGBoost4J Java API ================== diff --git a/doc/jvm/scaladocs/xgboost4j-flink/index.rst b/doc/jvm/scaladocs/xgboost4j-flink/index.rst index fe35703c0a54..e236c947b5c1 100644 --- a/doc/jvm/scaladocs/xgboost4j-flink/index.rst +++ b/doc/jvm/scaladocs/xgboost4j-flink/index.rst @@ -1,3 +1,5 @@ +:orphan: + ========================= XGBoost4J-Flink Scala API ========================= diff --git a/doc/jvm/scaladocs/xgboost4j-spark/index.rst b/doc/jvm/scaladocs/xgboost4j-spark/index.rst index c702f6e42196..1215f074c572 100644 --- a/doc/jvm/scaladocs/xgboost4j-spark/index.rst +++ b/doc/jvm/scaladocs/xgboost4j-spark/index.rst @@ -1,3 +1,5 @@ +:orphan: + ========================= XGBoost4J-Spark Scala API ========================= diff --git a/doc/jvm/scaladocs/xgboost4j/index.rst b/doc/jvm/scaladocs/xgboost4j/index.rst index 542dbc4d338b..2c19063e9194 100644 --- a/doc/jvm/scaladocs/xgboost4j/index.rst +++ b/doc/jvm/scaladocs/xgboost4j/index.rst @@ -1,3 +1,5 @@ +:orphan: + =================== XGBoost4J Scala API =================== diff --git a/doc/requirements.txt b/doc/requirements.txt index ddff9be928b6..9a2097035228 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -10,8 +10,8 @@ numpy scipy myst-parser ray[train] -xgboost_ray sphinx-gallery +dask pyspark cloudpickle setuptools diff --git a/doc/tutorials/ray.rst b/doc/tutorials/ray.rst index f3032c9705a6..1e9bc3fafa43 100644 --- a/doc/tutorials/ray.rst +++ b/doc/tutorials/ray.rst @@ -50,7 +50,7 @@ Using XGBoost-Ray for training and prediction XGBoost-Ray uses the same API as core XGBoost. There are only two differences: 1. Instead of using a ``xgboost.DMatrix``, you'll use a ``xgboost_ray.RayDMatrix`` object -2. There is an additional :class:`ray_params ` parameter that you can use to configure distributed training. +2. There is an additional ``xgboost_ray.RayParams`` parameter that you can use to configure distributed training. Simple training example ----------------------- @@ -88,7 +88,7 @@ and train a binary classifier using two actors. The only differences compared to the non-distributed API are the import statement (``xgboost_ray`` instead of ``xgboost``), using the -``RayDMatrix`` instead of the ``DMatrix``, and passing a :class:`RayParams ` object. +``RayDMatrix`` instead of the ``DMatrix``, and passing a ``xgboost_ray.RayParams`` object. The return object is a regular ``xgboost.Booster`` instance. @@ -115,10 +115,8 @@ will integrate this data in the correct order. The RayParams object ======================== -The ``RayParams`` object is used to configure various settings relating to -the distributed training. - -.. autoclass:: xgboost_ray.RayParams +The ``RayParams`` object is used to configure various settings relating to the distributed +training. Multi GPU training ================== @@ -175,7 +173,7 @@ away for the remainder of the training run, and don't have to wait until it is b In practice this usually leads to a very minor decrease in accuracy but a much shorter training time compared to non-elastic training. -Both training modes can be configured using the respective :class:`RayParams ` +Both training modes can be configured using the respective ``xgboost_ray.RayParams`` parameters. Hyperparameter optimization @@ -190,8 +188,7 @@ a few things you need to do: 1. Put your XGBoost-Ray training call into a function accepting parameter configurations (``train_model`` in the example below). -2. Create a :class:`RayParams ` object (``ray_params`` - in the example below). +2. Create a ``xgboost_ray.RayParams`` object (``ray_params`` in the example below). 3. Define the parameter search space (``config`` dict in the example below). 4. Call ``tune.run()``: * The ``metric`` parameter should contain the metric you'd like to optimize. diff --git a/ops/pipeline/build-r-docs-impl.sh b/ops/pipeline/build-r-docs-impl.sh new file mode 100755 index 000000000000..d61dbb9a2b27 --- /dev/null +++ b/ops/pipeline/build-r-docs-impl.sh @@ -0,0 +1,47 @@ +#!/bin/bash + +if [[ $# -ne 1 ]] +then + echo "Usage: $0 [branch name]" + exit 1 +fi + +branch_name=$1 + +if [[ -z "${R_LIBS_USER}" ]]; +then + export R_LIBS_USER=/tmp/rtmpdir +fi + +set -euo pipefail + +echo "R_LIBS_USER: ${R_LIBS_USER}" + +if [[ ! -d ${R_LIBS_USER} ]] +then + echo "Make ${R_LIBS_USER} for installing temporary R packages." + mkdir ${R_LIBS_USER} +fi + +# Used only in container environment +if command -v gosu 2>&1 >/dev/null +then + gosu root chown -R $UID:$GROUPS ${R_LIBS_USER} +fi + +cd R-package + +MAKEFLAGS=-j$(nproc) Rscript ./tests/helper_scripts/install_deps.R +# Some examples are failing +MAKEFLAGS=-j$(nproc) Rscript -e "pkgdown::build_site(examples=FALSE)" +# Install the package for vignettes +MAKEFLAGS=-j$(nproc) R CMD INSTALL . + +cd - + +cd doc/R-package +make -j$(nproc) all + +cd ../../ # back to project root + +tar cvjf r-docs-${branch_name}.tar.bz2 R-package/docs doc/R-package/xgboost_introduction.md doc/R-package/xgboostfromJSON.md diff --git a/ops/pipeline/build-r-docs.sh b/ops/pipeline/build-r-docs.sh new file mode 100755 index 000000000000..32af3a60fb43 --- /dev/null +++ b/ops/pipeline/build-r-docs.sh @@ -0,0 +1,19 @@ +#!/bin/bash + +set -euo pipefail + +if [[ -z ${BRANCH_NAME:-} ]] +then + echo "Make sure to define environment variable BRANCH_NAME." + exit 1 +fi + +source ops/pipeline/get-docker-registry-details.sh + +IMAGE_URI=${DOCKER_REGISTRY_URL}/xgb-ci.cpu_build_r_doc:main + +echo "--- Build R package doc" +set -x +python3 ops/docker_run.py \ + --image-uri ${IMAGE_URI} \ + -- ops/pipeline/build-r-docs-impl.sh ${BRANCH_NAME}