[docs][R] added R-package docs generation routines (#2176)

* added R-package docs generation routines

* change theme to be more consistent with sphinx_rtd_theme on main site in terms of color scheme

* placed man folder with old Rd files back

* specify full path to conda and make script more readable by one line - one pkg

* removed commented lines from build_r_site script

* made one line - one argument in build_reference() call

* pin R package versions

* fixed conflict

R-package/_pkgdown.yml

+template:
+  params:
+    bootswatch: cerulean
+
+site:
+  root: ''
+  title: LightGBM, Light Gradient Boosting Machine
+
+authors:
+  Guolin Ke:
+    href: https://github.com/guolinke
+    html: <img src="https://avatars0.githubusercontent.com/u/16040950?s=400&v=4" height="48" /> Guolin Ke
+  Damien Soukhavong:
+    href: https://github.com/Laurae2
+    html: <img src="https://avatars1.githubusercontent.com/u/9083669?s=460&v=4" height="48" /> Damien Soukhavong
+  Yachen Yan:
+    href: https://github.com/yanyachen
+    html: <img src="https://avatars1.githubusercontent.com/u/6893682?s=460&v=4" height="48" /> Yachen Yan
+  James Lamb:
+    href: https://github.com/jameslamb
+    html: <img src="https://avatars1.githubusercontent.com/u/7608904?s=400&v=4" height="48" /> James Lamb
+
+navbar:
+  title: LightGBM
+  type: default
+  left:
+  - icon: fa-reply fa-lg
+    href: ../
+  - icon: fa-home fa-lg
+    href: index.html
+  - text: Reference
+    href: reference/index.html
+  right:
+  - icon: fa-github fa-lg
+    href: https://github.com/microsoft/LightGBM/tree/master/R-package
+
+reference:
+  - title: Datasets
+    desc: Datasets included with the R package
+    contents:
+    - '`agaricus.train`'
+    - '`agaricus.test`'
+    - '`bank`'
+  - title: Data Input / Output
+    desc: Data I/O required for LightGBM
+    contents:
+    - '`dim.lgb.Dataset`'
+    - '`dimnames.lgb.Dataset`'
+    - '`getinfo`'
+    - '`setinfo`'
+    - '`slice`'
+    - '`lgb.Dataset`'
+    - '`lgb.Dataset.construct`'
+    - '`lgb.Dataset.create.valid`'
+    - '`lgb.Dataset.save`'
+    - '`lgb.Dataset.set.categorical`'
+    - '`lgb.Dataset.set.reference`'
+  - title: Machine Learning
+    desc: Train models with LightGBM
+    contents:
+    - '`lgb.prepare`'
+    - '`lgb.prepare2`'
+    - '`lgb.prepare_rules`'
+    - '`lgb.prepare_rules2`'
+    - '`lgb.train`'
+    - '`lgb.cv`'
+  - title: Saving / Loading Models
+    desc: Save and load LightGBM models
+    contents:
+    - '`lgb.dump`'
+    - '`lgb.save`'
+    - '`lgb.load`'
+    - '`lgb.model.dt.tree`'
+    - '`predict.lgb.Booster`'
+    - '`saveRDS.lgb.Booster`'
+    - '`readRDS.lgb.Booster`'
+  - title: Predictive Analysis
+    desc: Analyze your predictions
+    contents:
+    - '`lgb.get.eval.result`'
+    - '`lgb.importance`'
+    - '`lgb.interprete`'
+    - '`lgb.plot.importance`'
+    - '`lgb.plot.interpretation`'
+  - title: Miscellaneous
+    desc: Ungroupable functions to troubleshoot LightGBM
+    contents:
+    - '`lgb.unloader`'

build_r.R

@@ -56,7 +56,7 @@ result <- file.copy(from = "CMakeLists.txt",
                     overwrite = TRUE)
 .handle_result(result)
 
-# Build the package
+# Build the package (do not touch this line!)
 # NOTE: --keep-empty-dirs is necessary to keep the deep paths expected
 #       by CMake while also meeting the CRAN req to create object files
 #       on demand

build_r_site.R

+library(pkgdown)
+
+setwd("lightgbm_r")
+if (!dir.exists("docs")) {
+  dir.create("docs")
+}
+
+devtools::document()
+clean_site()
+init_site()
+build_home(preview = FALSE, quiet = FALSE)
+build_reference(lazy = FALSE,
+                document = FALSE,
+                examples = TRUE,
+                run_dont_run = FALSE,
+                seed = 42,
+                preview = FALSE)

docs/.linkcheckerrc

@@ -8,6 +8,7 @@ ignore=
   public.tableau.com
   https://www.open-mpi.org
   https://readthedocs.org
+  .*R/reference$
 ignorewarnings=http-robots-denied,https-certificate-error
 
 [output]

docs/R-API.rst

+R API
+=====
+
+Refer to `R reference <./R/reference>`__.

docs/README.rst

@@ -20,6 +20,9 @@ You can build the documentation locally. Just install Doxygen and run in ``docs`
     pip install -r requirements.txt
     make html
 
+Unfortunately, documentation for R code is built only on our site, and commands above will not build it for you locally.
+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:
 
 .. code:: sh

docs/conf.py

@@ -22,6 +22,7 @@ import os
 import sys
 import sphinx
 
+from distutils.dir_util import copy_tree
 from docutils.parsers.rst import Directive
 from sphinx.errors import VersionRequirementError
 from subprocess import PIPE, Popen
@@ -56,6 +57,7 @@ class IgnoredDirective(Directive):
 
 os.environ['LIGHTGBM_BUILD_DOC'] = '1'
 C_API = os.environ.get('C_API', '').lower().strip() != 'no'
+RTD = bool(os.environ.get('READTHEDOCS', ''))
 
 # If your documentation needs a minimal Sphinx version, state it here.
 needs_sphinx = '1.3'  # Due to sphinx.ext.napoleon
@@ -212,6 +214,52 @@ def generate_doxygen_xml(app):
         raise Exception("An error has occurred while executing Doxygen\n" + str(e))
 
 
+def generate_r_docs(app):
+    """Generate documentation for R-package.
+
+    Parameters
+    ----------
+    app : object
+        The application object representing the Sphinx process.
+    """
+    commands = """
+    echo 'options(repos = "https://cran.rstudio.com")' > $HOME/.Rprofile
+    /home/docs/.conda/bin/conda create -q -y -n r_env \
+        r-base=3.5.1=h1e0a451_2 \
+        r-devtools=1.13.6=r351h6115d3f_0 \
+        r-data.table=1.11.4=r351h96ca727_0 \
+        r-jsonlite=1.5=r351h96ca727_0 \
+        r-magrittr=1.5=r351h6115d3f_4 \
+        r-matrix=1.2_14=r351h96ca727_0 \
+        r-testthat=2.0.0=r351h29659fb_0 \
+        cmake=3.14.0=h52cb24c_0
+    /home/docs/.conda/bin/conda install -q -y -n r_env -c conda-forge \
+        r-pkgdown=1.3.0=r351h6115d3f_1000
+    source /home/docs/.conda/bin/activate r_env
+    export TAR=/bin/tar
+    cd {0}
+    sed -i'.bak' '/# Build the package (do not touch this line!)/q' build_r.R
+    Rscript build_r.R
+    Rscript build_r_site.R
+    """.format(os.path.join(CURR_PATH, os.path.pardir))
+    try:
+        # 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
+        # /blob/fe7644829057af622e467bb529db6c03a830da99/exhale/deploy.py#L99-L111
+        process = Popen(['/bin/bash'],
+                        stdin=PIPE, stdout=PIPE, stderr=PIPE,
+                        universal_newlines=True)
+        stdout, stderr = process.communicate(commands)
+        output = '\n'.join([i for i in (stdout, stderr) if i is not None])
+        if process.returncode != 0:
+            raise RuntimeError(output)
+        else:
+            print(output)
+    except BaseException as e:
+        raise Exception("An error has occurred while generating documentation for R-package\n" + str(e))
+
+
 def setup(app):
     """Add new elements at Sphinx initialization time.
 
@@ -220,9 +268,18 @@ def setup(app):
     app : object
         The application object representing the Sphinx process.
     """
+    first_run = not os.path.exists(os.path.join(CURR_PATH, '_FIRST_RUN.flag'))
+    if first_run and RTD:
+        open(os.path.join(CURR_PATH, '_FIRST_RUN.flag'), 'w').close()
     if C_API:
         app.connect("builder-inited", generate_doxygen_xml)
     else:
         app.add_directive('doxygenfile', IgnoredDirective)
+    if RTD:  # build R docs only on Read the Docs site
+        if first_run:
+            app.connect("builder-inited", generate_r_docs)
+        app.connect("build-finished",
+                    lambda app, exception: copy_tree(os.path.join(CURR_PATH, os.path.pardir, "lightgbm_r", "docs"),
+                                                     os.path.join(app.outdir, "R"), verbose=0))
     add_js_file = getattr(app, 'add_js_file', False) or app.add_javascript
     add_js_file("js/script.js")

docs/index.rst

@@ -29,6 +29,7 @@ For more details, please refer to `Features <./Features.rst>`__.
    Parameters Tuning <Parameters-Tuning>
    C API <C-API>
    Python API <Python-API>
+   R API <R-API>
    Parallel Learning Guide <Parallel-Learning-Guide>
    GPU Tutorial <GPU-Tutorial>
    Advanced Topics <Advanced-Topics>