conf.py 11.5 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
import datetime
21
22
import os
import sys
23
from pathlib import Path
24
from re import compile
25
from shutil import copytree
26
from subprocess import PIPE, Popen
27
from typing import Any, List
28
29

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

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

40
41
INTERNAL_REF_REGEX = compile(r"(?P<url>\.\/.+)(?P<extension>\.rst)(?P<anchor>$|#)")

42

43
44
45
46
47
48
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."""

49
    def apply(self, **kwargs: Any) -> None:
50
51
52
53
54
55
        """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"])


56
57
58
59
60
class IgnoredDirective(Directive):
    """Stub for unknown directives."""

    has_content = True

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


66
67
# -- General configuration ------------------------------------------------

68
os.environ['LIGHTGBM_BUILD_DOC'] = '1'
69
C_API = os.environ.get('C_API', '').lower().strip() != 'no'
70
RTD = bool(os.environ.get('READTHEDOCS', ''))
71

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

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

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

115
# Generate autosummary pages. Output should be set with: `:toctree: pythonapi/`
116
117
118
119
autosummary_generate = ['Python-API.rst']

# Only the class' docstring is inserted.
autoclass_content = 'class'
120

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

# The master toctree document.
master_doc = 'index'

# General information about the project.
project = 'LightGBM'
129
copyright = f'{datetime.datetime.now().year}, Microsoft Corporation'
130
131
author = 'Microsoft Corporation'

132
133
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
134
html_logo = str(CURR_PATH / 'logo' / 'LightGBM_logo_grey_text.svg')
135
136
137
138

# 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.
139
html_favicon = str(CURR_PATH / '_static' / 'images' / 'favicon.ico')
140

141
142
143
# 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.
144
145
146
147
# The short X.Y version.
version = (CURR_PATH.parent / 'VERSION.txt').read_text(encoding='utf-8').strip().replace('rc', '-rc')
# The full version, including alpha/beta/rc tags.
release = version
148
149
150
151
152
153

# 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.
154
language = 'en'
155
156
157
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
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The name of the Pygments (syntax highlighting) style to use.
162
pygments_style = 'default'
163

164
165
166
167
168
169
170
# -- Configuration for C API docs generation ------------------------------

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

180
181
182
183
184
185
186
187
188
# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'

# 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.
189
190
html_theme_options = {
    'includehidden': False,
191
    'logo_only': True,
192
}
193
194
195
196
197
198
199
200
201
202
203

# 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".
html_static_path = ['_static']

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

# Output file base name for HTML help builder.
htmlhelp_basename = 'LightGBMdoc'

204
205
206
207
# -- Options for LaTeX output ---------------------------------------------

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

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

215
def generate_doxygen_xml(app: Sphinx) -> None:
216
217
218
219
    """Generate XML documentation for C API by Doxygen.

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


261
def generate_r_docs(app: Sphinx) -> None:
262
263
264
265
    """Generate documentation for R-package.

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


313
def setup(app: Sphinx) -> None:
314
315
316
317
    """Add new elements at Sphinx initialization time.

    Parameters
    ----------
318
    app : sphinx.application.Sphinx
319
320
        The application object representing the Sphinx process.
    """
321
    first_run = not (CURR_PATH / '_FIRST_RUN.flag').exists()
322
    if first_run and RTD:
323
        (CURR_PATH / '_FIRST_RUN.flag').touch()
324
325
326
327
    if C_API:
        app.connect("builder-inited", generate_doxygen_xml)
    else:
        app.add_directive('doxygenfile', IgnoredDirective)
328
329
330
331
    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",
332
333
                    lambda app, _: copytree(CURR_PATH.parent / "lightgbm_r" / "docs",
                                            Path(app.outdir) / "R"))
334
    app.add_transform(InternalRefTransform)
335
336
    add_js_file = getattr(app, 'add_js_file', False) or app.add_javascript
    add_js_file("js/script.js")