conf.py 12.1 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# LightGBM documentation build configuration file, created by
# sphinx-quickstart on Thu May  4 14:30:58 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
18
# documentation root, use os.path.abspath to make it absolute.
19
"""Sphinx configuration file."""
20

21
import datetime
22
23
import os
import sys
24
from pathlib import Path
25
from re import compile
26
from shutil import copytree
27
from subprocess import PIPE, Popen
28
from typing import Any, List
29
30

import sphinx
31
from docutils.nodes import reference
32
from docutils.parsers.rst import Directive
33
from docutils.transforms import Transform
34
from sphinx.application import Sphinx
35
from sphinx.errors import VersionRequirementError
36

37
CURR_PATH = Path(__file__).absolute().parent
38
LIB_PATH = CURR_PATH.parent / "python-package"
39
sys.path.insert(0, str(LIB_PATH))
40

41
INTERNAL_REF_REGEX = compile(r"(?P<url>\.\/.+)(?P<extension>\.rst)(?P<anchor>$|#)")
42
RTD_R_REF_REGEX = compile(r"(?P<begin>https://.+/)(?P<rtd_version>latest)(?P<end>/R/reference/)")
43

44

45
46
47
48
49
50
class InternalRefTransform(Transform):
    """Replaces '.rst' with '.html' in all internal links like './[Something].rst[#anchor]'."""

    default_priority = 210
    """Numerical priority of this transform, 0 through 999."""

51
    def apply(self, **kwargs: Any) -> None:
52
53
54
55
56
57
        """Apply the transform to the document tree."""
        for section in self.document.traverse(reference):
            if section.get("refuri") is not None:
                section["refuri"] = INTERNAL_REF_REGEX.sub(r"\g<url>.html\g<anchor>", section["refuri"])


58
59
60
61
62
class IgnoredDirective(Directive):
    """Stub for unknown directives."""

    has_content = True

63
    def run(self) -> List:
64
65
66
67
        """Do nothing."""
        return []


68
69
# -- General configuration ------------------------------------------------

70
71
72
os.environ["LIGHTGBM_BUILD_DOC"] = "1"
C_API = os.environ.get("C_API", "").lower().strip() != "no"
RTD = bool(os.environ.get("READTHEDOCS", ""))
73
RTD_VERSION = os.environ.get("READTHEDOCS_VERSION", "stable")
74

75
# If your documentation needs a minimal Sphinx version, state it here.
76
needs_sphinx = "2.1.0"  # Due to sphinx.ext.napoleon, autodoc_typehints
77
if needs_sphinx > sphinx.__version__:
78
    message = f"This project needs at least Sphinx v{needs_sphinx}"
79
    raise VersionRequirementError(message)
80
81
82
83
84

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
85
86
87
88
89
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.todo",
    "sphinx.ext.viewcode",
    "sphinx.ext.napoleon",
90
    "sphinx.ext.intersphinx",
91
92
]

93
autodoc_default_flags = ["members", "inherited-members", "show-inheritance"]
94
95
96
97
98
autodoc_default_options = {
    "members": True,
    "inherited-members": True,
    "show-inheritance": True,
}
99
100
# mock out modules
autodoc_mock_imports = [
101
102
103
104
105
106
107
108
109
    "dask",
    "dask.distributed",
    "datatable",
    "graphviz",
    "matplotlib",
    "numpy",
    "pandas",
    "scipy",
    "scipy.sparse",
110
]
111
try:
112
    import sklearn  # noqa: F401
113
except ImportError:
114
    autodoc_mock_imports.append("sklearn")
115
116
117
# hide type hints in API docs
autodoc_typehints = "none"

118
# Generate autosummary pages. Output should be set with: `:toctree: pythonapi/`
119
autosummary_generate = ["Python-API.rst"]
120
121

# Only the class' docstring is inserted.
122
autoclass_content = "class"
123

124
125
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
126
127

# The master toctree document.
128
master_doc = "index"
129
130

# General information about the project.
131
132
133
project = "LightGBM"
copyright = f"{datetime.datetime.now().year}, Microsoft Corporation"
author = "Microsoft Corporation"
134

135
136
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
137
html_logo = str(CURR_PATH / "logo" / "LightGBM_logo_grey_text.svg")
138
139
140
141

# The name of an image file (relative to this directory) to use as a favicon of
# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
142
html_favicon = str(CURR_PATH / "_static" / "images" / "favicon.ico")
143

144
145
146
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
147
# The short X.Y version.
148
version = (CURR_PATH.parent / "VERSION.txt").read_text(encoding="utf-8").strip().replace("rc", "-rc")
149
150
# The full version, including alpha/beta/rc tags.
release = version
151
152
153
154
155
156

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
157
language = "en"
158
159
160
161

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
162
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
163
164

# The name of the Pygments (syntax highlighting) style to use.
165
pygments_style = "default"
166

167
168
169
# -- Configuration for C API docs generation ------------------------------

if C_API:
170
171
172
173
174
175
    extensions.extend(
        [
            "breathe",
        ]
    )
    breathe_projects = {"LightGBM": str(CURR_PATH / "doxyoutput" / "xml")}
176
177
178
179
180
    breathe_default_project = "LightGBM"
    breathe_domain_by_extension = {
        "h": "c",
    }
    breathe_show_define_initializer = True
181
    c_id_attributes = ["LIGHTGBM_C_EXPORT"]
182

183
184
185
186
# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
187
html_theme = "sphinx_rtd_theme"
188
189
190
191

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
192
html_theme_options = {
193
194
    "includehidden": False,
    "logo_only": True,
195
}
196
197
198
199

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
200
html_static_path = ["_static"]
201
202
203
204

# -- Options for HTMLHelp output ------------------------------------------

# Output file base name for HTML help builder.
205
htmlhelp_basename = "LightGBMdoc"
206

207
208
209
210
# -- Options for LaTeX output ---------------------------------------------

# The name of an image file (relative to this directory) to place at the top of
# the title page.
211
latex_logo = str(CURR_PATH / "logo" / "LightGBM_logo_black_text_small.png")
212

213
214
215
216
# intersphinx configuration
intersphinx_mapping = {
    "sklearn": ("https://scikit-learn.org/stable/", None),
}
217

218

219
def generate_doxygen_xml(app: Sphinx) -> None:
220
221
222
223
    """Generate XML documentation for C API by Doxygen.

    Parameters
    ----------
224
    app : sphinx.application.Sphinx
225
226
227
        The application object representing the Sphinx process.
    """
    doxygen_args = [
228
229
        f"INPUT={CURR_PATH.parent / 'include' / 'LightGBM' / 'c_api.h'}",
        f"OUTPUT_DIRECTORY={CURR_PATH / 'doxyoutput'}",
230
231
232
233
234
235
236
237
238
239
240
        "GENERATE_HTML=NO",
        "GENERATE_LATEX=NO",
        "GENERATE_XML=YES",
        "XML_OUTPUT=xml",
        "XML_PROGRAMLISTING=YES",
        r'ALIASES="rst=\verbatim embed:rst:leading-asterisk"',
        r'ALIASES+="endrst=\endverbatim"',
        "ENABLE_PREPROCESSING=YES",
        "MACRO_EXPANSION=YES",
        "EXPAND_ONLY_PREDEF=NO",
        "SKIP_FUNCTION_MACROS=NO",
241
        "PREDEFINED=__cplusplus",
242
243
244
        "SORT_BRIEF_DOCS=YES",
        "WARN_AS_ERROR=YES",
    ]
245
    doxygen_input = "\n".join(doxygen_args)
246
    doxygen_input = bytes(doxygen_input, "utf-8")
247
    (CURR_PATH / "doxyoutput").mkdir(parents=True, exist_ok=True)
248
249
250
251
252
    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
253
        process = Popen(["doxygen", "-"], stdin=PIPE, stdout=PIPE, stderr=PIPE)
254
        stdout, stderr = process.communicate(doxygen_input)
255
        output = "\n".join([i.decode("utf-8") for i in (stdout, stderr) if i is not None])
256
257
258
259
260
        if process.returncode != 0:
            raise RuntimeError(output)
        else:
            print(output)
    except BaseException as e:
261
        raise Exception(f"An error has occurred while executing Doxygen\n{e}")
262
263


264
def generate_r_docs(app: Sphinx) -> None:
265
266
267
268
    """Generate documentation for R-package.

    Parameters
    ----------
269
    app : sphinx.application.Sphinx
270
271
        The application object representing the Sphinx process.
    """
272
    commands = f"""
273
    export TAR=/bin/tar
274
    cd {CURR_PATH.parent}
275
    export R_LIBS="$CONDA_PREFIX/lib/R/library"
276
277
    sh build-cran-package.sh || exit 1
    R CMD INSTALL --with-keep.source lightgbm_*.tar.gz || exit 1
278
279
280
    cp -R \
        {CURR_PATH.parent / "R-package" / "pkgdown"} \
        {CURR_PATH.parent / "lightgbm_r" / "pkgdown"}
281
    cd {CURR_PATH.parent / "lightgbm_r"}
282
    Rscript -e "roxygen2::roxygenize(load = 'installed')" || exit 1
283
284
285
286
287
    Rscript -e "pkgdown::build_site( \
            lazy = FALSE \
            , install = FALSE \
            , devel = FALSE \
            , examples = TRUE \
288
            , run_dont_run = TRUE \
289
290
291
            , seed = 42L \
            , preview = FALSE \
            , new_process = TRUE \
292
        )
293
        " || exit 1
294
    cd {CURR_PATH.parent}
295
    """
296
    try:
297
        print("Building R-package documentation")
298
299
300
301
        # 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
302
        process = Popen(["/bin/bash"], stdin=PIPE, stdout=PIPE, stderr=PIPE, universal_newlines=True)
303
        stdout, stderr = process.communicate(commands)
304
        output = "\n".join([i for i in (stdout, stderr) if i is not None])
305
306
307
308
        if process.returncode != 0:
            raise RuntimeError(output)
        else:
            print(output)
309
            print("Done building R-package documentation")
310
    except BaseException as e:
311
        raise Exception(f"An error has occurred while generating documentation for R-package\n{e}")
312
313


314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def replace_reference_to_r_docs(app: Sphinx) -> None:
    """Make reference to R-package documentation point to the actual version.

    Parameters
    ----------
    app : sphinx.application.Sphinx
        The application object representing the Sphinx process.
    """
    index_doc_path = CURR_PATH / "index.rst"
    with open(index_doc_path, "r+t", encoding="utf-8") as index_doc:
        content = index_doc.read()
        content = RTD_R_REF_REGEX.sub(rf"\g<begin>{RTD_VERSION}\g<end>", content)
        index_doc.seek(0)
        index_doc.write(content)


330
def setup(app: Sphinx) -> None:
331
332
333
334
    """Add new elements at Sphinx initialization time.

    Parameters
    ----------
335
    app : sphinx.application.Sphinx
336
337
        The application object representing the Sphinx process.
    """
338
    first_run = not (CURR_PATH / "_FIRST_RUN.flag").exists()
339
    if first_run and RTD:
340
        (CURR_PATH / "_FIRST_RUN.flag").touch()
341
342
343
    if C_API:
        app.connect("builder-inited", generate_doxygen_xml)
    else:
344
        app.add_directive("doxygenfile", IgnoredDirective)
345
346
347
    if RTD:  # build R docs only on Read the Docs site
        if first_run:
            app.connect("builder-inited", generate_r_docs)
348
349
350
        app.connect(
            "build-finished", lambda app, _: copytree(CURR_PATH.parent / "lightgbm_r" / "docs", Path(app.outdir) / "R")
        )
351
    app.connect("builder-inited", replace_reference_to_r_docs)
352
    app.add_transform(InternalRefTransform)
353
    add_js_file = getattr(app, "add_js_file", False) or app.add_javascript
354
    add_js_file("js/script.js")