Skip to content

Commit ebca332

Browse files
trivialfistrivialfis
authored
[doc] Reference the R doc in sphinx document site. (#11166)
1 parent f78aebb commit ebca332

File tree

23 files changed

+347
-67
lines changed

23 files changed

+347
-67
lines changed

‎.github/workflows/doc.yml

+48-1
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,25 @@ jobs:
1313
- runs-on=${{ github.run_id }}
1414
- runner=linux-amd64-cpu
1515
- tag=doc-build-jvm-docs
16+
1617
steps:
1718
# Restart Docker daemon so that it recognizes the ephemeral disks
1819
- run: sudo systemctl restart docker
1920
- uses: actions/checkout@v4
2021
with:
2122
submodules: "true"
23+
24+
- name: Get the git hash for the push event.
25+
if: ${{ github.event_name == 'push' }}
26+
shell: bash
27+
run: |
28+
echo "HEAD_SHA=${GITHUB_SHA}" >> ${GITHUB_ENV}
29+
- name: Get the git hash for the PR event.
30+
if: ${{ github.event_name == 'pull_request' }}
31+
shell: bash
32+
run: |
33+
echo "HEAD_SHA=${{ github.event.pull_request.head.sha }}" >> ${GITHUB_ENV}
34+
2235
- name: Log into Docker registry (AWS ECR)
2336
run: bash ops/pipeline/login-docker-registry.sh
2437
- run: bash ops/pipeline/build-jvm-gpu.sh
@@ -29,9 +42,43 @@ jobs:
2942
# branch can be the name of the dmlc/xgboost branch, or `PR-{number}`.
3043
python3 ops/pipeline/manage-artifacts.py upload \
3144
--s3-bucket xgboost-docs \
32-
--prefix ${BRANCH_NAME}/${GITHUB_SHA} --make-public \
45+
--prefix ${BRANCH_NAME}/${{ env.HEAD_SHA }} --make-public \
3346
jvm-packages/${{ env.BRANCH_NAME }}.tar.bz2
3447
48+
build-r-docs:
49+
name: Build docs for the R package
50+
runs-on:
51+
- runs-on=${{ github.run_id }}
52+
- runner=linux-amd64-cpu
53+
- tag=r-tests-build-docs
54+
steps:
55+
# Restart Docker daemon so that it recognizes the ephemeral disks
56+
- run: sudo systemctl restart docker
57+
- uses: actions/checkout@v4
58+
with:
59+
submodules: "true"
60+
61+
- name: Get the git hash for the push event.
62+
if: ${{ github.event_name == 'push' }}
63+
shell: bash
64+
run: |
65+
echo "HEAD_SHA=${GITHUB_SHA}" >> ${GITHUB_ENV}
66+
- name: Get the git hash for the PR event.
67+
if: ${{ github.event_name == 'pull_request' }}
68+
shell: bash
69+
run: |
70+
echo "HEAD_SHA=${{ github.event.pull_request.head.sha }}" >> ${GITHUB_ENV}
71+
72+
- name: Log into Docker registry (AWS ECR)
73+
run: bash ops/pipeline/login-docker-registry.sh
74+
- run: bash ops/pipeline/build-r-docs.sh
75+
- name: Upload R doc
76+
run: |
77+
python3 ops/pipeline/manage-artifacts.py upload \
78+
--s3-bucket xgboost-docs \
79+
--prefix ${BRANCH_NAME}/${{ env.HEAD_SHA }} --make-public \
80+
r-docs-${{ env.BRANCH_NAME }}.tar.bz2
81+
3582
trigger-rtd-build:
3683
needs: [build-jvm-docs]
3784
name: Trigger Read The Docs build.

‎.github/workflows/jvm_tests.yml

-30
Original file line numberDiff line numberDiff line change
@@ -95,36 +95,6 @@ jobs:
9595
AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID_IAM_S3_UPLOADER }}
9696
AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY_IAM_S3_UPLOADER }}
9797

98-
build-jvm-docs:
99-
name: Build docs for JVM packages
100-
needs: [build-jvm-gpu]
101-
runs-on:
102-
- runs-on=${{ github.run_id }}
103-
- runner=linux-amd64-cpu
104-
- tag=jvm-tests-build-jvm-docs
105-
steps:
106-
# Restart Docker daemon so that it recognizes the ephemeral disks
107-
- run: sudo systemctl restart docker
108-
- uses: actions/checkout@v4
109-
with:
110-
submodules: "true"
111-
- name: Log into Docker registry (AWS ECR)
112-
run: bash ops/pipeline/login-docker-registry.sh
113-
- name: Unstash files
114-
run: |
115-
python3 ops/pipeline/manage-artifacts.py download \
116-
--s3-bucket ${{ env.RUNS_ON_S3_BUCKET_CACHE }} \
117-
--prefix cache/${{ github.run_id }}/build-jvm-gpu \
118-
--dest-dir lib \
119-
libxgboost4j.so
120-
- run: bash ops/pipeline/build-jvm-doc.sh
121-
- name: Upload JVM doc
122-
run: |
123-
python3 ops/pipeline/manage-artifacts.py upload \
124-
--s3-bucket xgboost-docs \
125-
--prefix ${BRANCH_NAME}/${GITHUB_SHA} --make-public \
126-
jvm-packages/${{ env.BRANCH_NAME }}.tar.bz2
127-
12898
build-test-jvm-packages:
12999
name: Build and test JVM packages (Linux, Scala ${{ matrix.scala_version }})
130100
runs-on:

‎R-package/.Rbuildignore

+3
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,6 @@
66
README.md
77
^doc$
88
^Meta$
9+
^_pkgdown\.yml$
10+
^docs$
11+
^pkgdown$

‎R-package/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs

‎R-package/README.md

+5-11
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
1-
XGBoost R Package for Scalable GBM
2-
==================================
1+
XGBoost R Package
2+
=================
33

44
[![CRAN Status Badge](http://www.r-pkg.org/badges/version/xgboost)](https://cran.r-project.org/web/packages/xgboost)
55
[![CRAN Downloads](http://cranlogs.r-pkg.org/badges/xgboost)](https://cran.rstudio.com/web/packages/xgboost/index.html)
6-
[![Documentation Status](https://readthedocs.org/projects/xgboost/badge/?version=latest)](http://xgboost.readthedocs.org/en/latest/R-package/index.html)
6+
[![Documentation Status](https://readthedocs.org/projects/xgboost/badge/?version=latest)](https://xgboost.readthedocs.org/en/latest/R-package/index.html)
77

88
Resources
99
---------
10-
* [XGBoost R Package Online Documentation](http://xgboost.readthedocs.org/en/latest/R-package/index.html)
10+
* [XGBoost R Package Online Documentation](https://xgboost.readthedocs.org/en/stable/R-package/index.html)
1111
- Check this out for detailed documents, examples and tutorials.
1212

1313
Installation
@@ -19,13 +19,7 @@ We are [on CRAN](https://cran.r-project.org/web/packages/xgboost/index.html) now
1919
install.packages('xgboost')
2020
```
2121

22-
For more detailed installation instructions, please see [here](http://xgboost.readthedocs.org/en/latest/build.html#r-package-installation).
23-
24-
Examples
25-
--------
26-
27-
* Please visit [walk through example](demo).
28-
* 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).
22+
For more detailed installation instructions, please see [here](https://xgboost.readthedocs.io/en/stable/install.html).
2923

3024
Development
3125
-----------

‎R-package/pkgdown/_pkgdown.yml

+92
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
url: https://github.com/dmlc/xgboost
2+
3+
template:
4+
bootstrap: 5
5+
math-rendering: mathjax
6+
7+
reference:
8+
- title: High Level Interface
9+
desc: High level XGBoost interface
10+
contents:
11+
- "xgboost"
12+
- "predict.xgboost"
13+
- "print.xgboost"
14+
- title: Datasets
15+
desc: Test datasets bundled with the R package.
16+
contents:
17+
- "agaricus.train"
18+
- "agaricus.test"
19+
- title: Global Configuration
20+
desc: Global configuration for the XGBoost library.
21+
contents:
22+
- "xgb.config"
23+
- "xgb.set.config"
24+
- "xgb.get.config"
25+
- title: DMatrix
26+
desc: Low-level data storage.
27+
contents:
28+
- "xgb.DMatrix"
29+
- "xgb.DMatrix.hasinfo"
30+
- "xgb.DMatrix.save"
31+
- "dim.xgb.DMatrix"
32+
- "dimnames.xgb.DMatrix"
33+
- "print.xgb.DMatrix"
34+
- "xgb.DataBatch"
35+
- "xgb.DataIter"
36+
- "xgb.get.DMatrix.data"
37+
- "xgb.get.DMatrix.num.non.missing"
38+
- "xgb.ExtMemDMatrix"
39+
- "xgb.QuantileDMatrix.from_iterator"
40+
- "xgb.get.DMatrix.qcut"
41+
- "xgb.slice.DMatrix"
42+
- title: Booster
43+
desc: The model for XGBoost.
44+
contents:
45+
- "a-compatibility-note-for-saveRDS-save"
46+
- "coef.xgb.Booster"
47+
- "getinfo.xgb.Booster"
48+
- "predict.xgb.Booster"
49+
- "print.xgb.Booster"
50+
- "xgb.load"
51+
- "xgb.load.raw"
52+
- "xgb.save"
53+
- "xgb.save.raw"
54+
- "xgb.copy.Booster"
55+
- "xgb.slice.Booster"
56+
- "xgb.get.num.boosted.rounds"
57+
- "xgb.is.same.Booster"
58+
- "xgb.importance"
59+
- "xgb.attr"
60+
- "xgb.create.features"
61+
- "xgb.model.dt.tree"
62+
- "xgb.model.parameters<-"
63+
- "xgb.ggplot.deepness"
64+
- "xgb.dump"
65+
- "variable.names.xgb.Booster"
66+
- "xgb.ggplot.importance"
67+
- "xgb.plot.multi.trees"
68+
- "xgb.plot.shap"
69+
- "xgb.ggplot.shap.summary"
70+
- "xgb.plot.tree"
71+
- "xgb.gblinear.history"
72+
- title: Training Callbacks
73+
desc: Callback functions used for training.
74+
contents:
75+
- "xgb.Callback"
76+
- "xgb.cb.cv.predict"
77+
- "xgb.cb.early.stop"
78+
- "xgb.cb.evaluation.log"
79+
- "xgb.cb.gblinear.history"
80+
- "xgb.cb.print.evaluation"
81+
- "xgb.cb.reset.parameters"
82+
- "xgb.cb.save.model"
83+
- title: Low-level Training Functions
84+
desc: Low-level Training Functions with DMatrix and Booster
85+
contents:
86+
- "xgb.params"
87+
- "xgb.train"
88+
- "xgb.cv"
89+
- "print.xgb.cv.synchronous"
90+
- title: Deprecation Settings
91+
contents:
92+
- "xgboost-options"

‎R-package/tests/helper_scripts/install_deps.R

-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,6 @@ pkgs <- c(
2626
"RhpcBLASctl",
2727
## imports
2828
"Matrix",
29-
"methods",
3029
"data.table",
3130
"jsonlite"
3231
)

‎R-package/vignettes/xgboost_introduction.Rmd

+9-6
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,10 @@ output:
1212
toc_float: true
1313
---
1414

15-
# Introduction
15+
XGBoost for R introduction
16+
==========================
17+
18+
## Introduction
1619

1720
**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.
1821

@@ -22,7 +25,7 @@ For more details about XGBoost's features and usage, see the [online documentati
2225

2326
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.
2427

25-
# Building a predictive model
28+
## Building a predictive model
2629

2730
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.
2831

@@ -62,7 +65,7 @@ model_abserr <- xgboost(x, y, objective = "reg:absoluteerror", nthreads = 1, nro
6265

6366
_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._
6467

65-
# Model parameters
68+
## Model parameters
6669

6770
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.
6871

@@ -105,7 +108,7 @@ xgboost(
105108
)
106109
```
107110

108-
# Examining model objects
111+
## Examining model objects
109112

110113
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()`:
111114

@@ -131,7 +134,7 @@ xgb.importance(model)
131134
xgb.model.dt.tree(model)
132135
```
133136

134-
# Other features
137+
## Other features
135138

136139
XGBoost supports many additional features on top of its traditional gradient-boosting framework, including, among others:
137140

@@ -143,7 +146,7 @@ XGBoost supports many additional features on top of its traditional gradient-boo
143146

144147
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.
145148

146-
# The low-level interface
149+
## The low-level interface
147150

148151
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.
149152

‎doc/R-package/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
*~
2+
*.md

‎doc/R-package/Makefile

+2
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ PKGROOT=../../R-package
55
xgboostfromJSON.md: $(PKGROOT)/vignettes/xgboostfromJSON.Rmd
66
xgboost_introduction.md: $(PKGROOT)/vignettes/xgboost_introduction.Rmd
77

8+
all: xgboostfromJSON.md xgboost_introduction.md
9+
810
# General Rules for build rmarkdowns, need knitr
911
%.md:
1012
Rscript -e \

‎doc/R-package/index.rst

+16-3
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,32 @@ XGBoost R Package
99

1010
You have found the XGBoost R Package!
1111

12+
.. toctree::
13+
:maxdepth: 2
14+
:titlesonly:
15+
1216
***********
1317
Get Started
1418
***********
19+
1520
* Checkout the :doc:`Installation Guide </install>` contains instructions to install xgboost, and :doc:`Tutorials </tutorials/index>` for examples on how to use XGBoost for various tasks.
16-
* Read the `API documentation <https://cran.r-project.org/web/packages/xgboost/xgboost.pdf>`_.
21+
* 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.
22+
* Read the `CRAN documentation <https://cran.r-project.org/web/packages/xgboost/xgboost.pdf>`_.
23+
24+
*********
25+
Vignettes
26+
*********
27+
28+
.. toctree::
29+
30+
xgboost_introduction
31+
xgboostfromJSON
1732

1833
************
1934
Other topics
2035
************
2136

2237
.. toctree::
23-
:maxdepth: 2
24-
:titlesonly:
2538

2639
Migrating code from previous XGBoost versions <migration_guide>
2740
Handling of indexable elements <index_base>

‎doc/R-package/r_docs/index.rst

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
:orphan:
2+
3+
=============
4+
XGBoost R API
5+
=============

0 commit comments

Comments
 (0)