conf.py 12.2 KB
Newer Older
Yan Ni's avatar
Yan Ni committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config

# -- Path setup --------------------------------------------------------------

# 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
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
15
import os
Yuge Zhang's avatar
Yuge Zhang committed
16
import re
17
import subprocess
18
import sys
19
sys.path.insert(0, os.path.abspath('../..'))
20
sys.path.insert(0, os.path.abspath('../extension'))
Yan Ni's avatar
Yan Ni committed
21
22
23
24


# -- Project information ---------------------------------------------------

Yuge Zhang's avatar
Yuge Zhang committed
25
from datetime import datetime
26
project = 'NNI'
Yuge Zhang's avatar
Yuge Zhang committed
27
copyright = f'{datetime.now().year}, Microsoft'
Yan Ni's avatar
Yan Ni committed
28
29
30
31
32
author = 'Microsoft'

# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
Yuge Zhang's avatar
Yuge Zhang committed
33
# FIXME: this should be written somewhere globally
J-shang's avatar
J-shang committed
34
release = 'v2.7'
Yan Ni's avatar
Yan Ni committed
35
36
37
38
39
40
41
42
43
44
45

# -- General configuration ---------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
46
    'sphinx_gallery.gen_gallery',
Yan Ni's avatar
Yan Ni committed
47
    'sphinx.ext.autodoc',
Yuge Zhang's avatar
Yuge Zhang committed
48
    'sphinx.ext.autosummary',
liuzhe-lz's avatar
liuzhe-lz committed
49
    'sphinx.ext.intersphinx',
Yan Ni's avatar
Yan Ni committed
50
    'sphinx.ext.mathjax',
51
    'sphinxarg4nni.ext',
Yan Ni's avatar
Yan Ni committed
52
    'sphinx.ext.napoleon',
53
    'sphinx.ext.viewcode',
54
    'sphinx.ext.intersphinx',
Yuge Zhang's avatar
Yuge Zhang committed
55
    'sphinxcontrib.bibtex',
56
    # 'nbsphinx',  # nbsphinx has conflicts with sphinx-gallery.
57
    'sphinx.ext.extlinks',
58
    'IPython.sphinxext.ipython_console_highlighting',
59
60
    'sphinx_tabs.tabs',
    'sphinx_copybutton',
61
62

    # Custom extensions in extension/ folder.
Yuge Zhang's avatar
Yuge Zhang committed
63
    'tutorial_links',  # this has to be after sphinx-gallery
64
    'getpartialtext',
65
66
    'inplace_translation',
    'cardlinkitem',
67
    'codesnippetcard',
Yuge Zhang's avatar
Yuge Zhang committed
68
    'patch_autodoc',
69
    'toctree_check',
Yan Ni's avatar
Yan Ni committed
70
71
]

Yuge Zhang's avatar
Yuge Zhang committed
72
73
74
75
76
77
78
# Autosummary related settings
autosummary_imported_members = True
autosummary_ignore_module_all = False

# Auto-generate stub files before building docs
autosummary_generate = True

79
# Add mock modules
80
81
82
83
autodoc_mock_imports = [
    'apex', 'nni_node', 'tensorrt', 'pycuda', 'nn_meter', 'azureml',
    'ConfigSpace', 'ConfigSpaceNNI', 'smac', 'statsmodels', 'pybnn',
]
Yuge Zhang's avatar
Yuge Zhang committed
84

85
# Some of our modules cannot generate summary
Yuge Zhang's avatar
Yuge Zhang committed
86
87
88
89
90
autosummary_mock_imports = [
    'nni.retiarii.codegen.tensorflow',
    'nni.nas.benchmarks.nasbench101.db_gen',
    'nni.tools.jupyter_extension.management',
] + autodoc_mock_imports
91

liuzhe-lz's avatar
liuzhe-lz committed
92
93
94
95
autodoc_typehints = 'description'
autodoc_typehints_description_target = 'documented'
autodoc_inherit_docstrings = False

96
97
98
# Sphinx will warn about all references where the target cannot be found.
nitpicky = False  # disabled for now

Yuge Zhang's avatar
Yuge Zhang committed
99
100
101
102
103
104
105
106
107
108
# A list of regular expressions that match URIs that should not be checked.
linkcheck_ignore = [
    r'http://localhost:\d+',
    r'.*://.*/#/',                          # Modern websites that has URLs like xxx.com/#/guide
    r'https://github.com/JSong-Jia/Pic/',   # Community links can't be found any more
]

# Ignore all links located in release.rst
linkcheck_exclude_documents = ['^release']

Yuge Zhang's avatar
Yuge Zhang committed
109
110
111
112
113
114
115
116
117
# Bibliography files
bibtex_bibfiles = ['refs.bib']

# Add a heading to bibliography
bibtex_footbibliography_header = '.. rubric:: Bibliography'

# Set bibliography style
bibtex_default_style = 'plain'

118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
# Sphinx gallery examples
sphinx_gallery_conf = {
    'examples_dirs': '../../examples/tutorials',   # path to your example scripts
    'gallery_dirs': 'tutorials',                   # path to where to save gallery generated output

    # Control ignored python files.
    'ignore_pattern': r'__init__\.py|/scripts/',

    # This is `/plot` by default. Only files starting with `/plot` will be executed.
    # All files should be executed in our case.
    'filename_pattern': r'.*',

    # Disabling download button of all scripts
    'download_all_examples': False,

    # Change default thumbnail
    # Working directory is strange, needs full path.
    'default_thumb_file': os.path.join(os.path.dirname(__file__), '../img/thumbnails/nni_icon_blue.png'),
}

138
139
140
141
# Copybutton: strip and configure input prompts for code cells.
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
copybutton_prompt_is_regexp = True

Yuge Zhang's avatar
Yuge Zhang committed
142
143
144
# Copybutton: customize selector to exclude gallery outputs.
copybutton_selector = ":not(div.sphx-glr-script-out) > div.highlight pre"

145
146
147
148
149
150
# Allow additional builders to be considered compatible.
sphinx_tabs_valid_builders = ['linkcheck']

# Disallow the sphinx tabs css from loading.
sphinx_tabs_disable_css_loading = True

151
152
153
154
155
156
# Some tutorials might need to appear more than once in toc.
# In this list, we make source/target tutorial pairs.
# Each "source" tutorial rst will be copied to "target" tutorials.
# The anchors will be replaced to avoid dupilcate labels.
# Target should start with ``cp_`` to be properly ignored in git.
tutorials_copy_list = [
157
158
159
160
161
162
163
164
165
166
167
168
169
170
    # Seems that we don't need it for now.
    # Add tuples back if we need it in future.
]

# Toctree ensures that toctree docs do not contain any other contents.
# Home page should be an exception.
toctree_check_whitelist = [
    'index',

    # FIXME: Other exceptions should be correctly handled.
    'compression/index',
    'compression/pruning',
    'compression/quantization',
    'hpo/hpo_benchmark',
171
172
]

Yan Ni's avatar
Yan Ni committed
173
# Add any paths that contain templates here, relative to this directory.
Yuge Zhang's avatar
Yuge Zhang committed
174
templates_path = ['../templates']
Yan Ni's avatar
Yan Ni committed
175
176
177

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
178
source_suffix = ['.rst']
Yan Ni's avatar
Yan Ni committed
179
180

# The master toctree document.
Yuge Zhang's avatar
Yuge Zhang committed
181
master_doc = 'index'
Yan Ni's avatar
Yan Ni committed
182
183
184
185
186
187
188
189

# 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.
language = None

190
191
192
193
194
195
196
197
198
199
200
201
# Translation related settings
locale_dir = ['locales']

# Documents that requires translation: https://github.com/microsoft/nni/issues/4298
gettext_documents = [
    r'^index$',
    r'^quickstart$',
    r'^installation$',
    r'^(nas|hpo|compression)/overview$',
    r'^tutorials/(hello_nas|pruning_quick_start_mnist|hpo_quickstart_pytorch/main)$',
]

Yan Ni's avatar
Yan Ni committed
202
203
204
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
205
206
207
208
209
210
211
212
213
214
exclude_patterns = [
    '_build',
    'Thumbs.db',
    '.DS_Store',
    '**.ipynb_checkpoints',
    # Exclude translations. They will be added back via replacement later if language is set.
    '**_zh.rst',
    # Exclude generated tutorials index
    'tutorials/index.rst',
]
Yan Ni's avatar
Yan Ni committed
215
216
217
218

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None

Yuge Zhang's avatar
Yuge Zhang committed
219
# -- Options for HTML output -------------------------------------------------
Yan Ni's avatar
Yan Ni committed
220

Yuge Zhang's avatar
Yuge Zhang committed
221
222
# HTML logo
html_logo = '../img/nni_icon.svg'
223

Yuge Zhang's avatar
Yuge Zhang committed
224
225
# HTML favicon
html_favicon = '../img/favicon.ico'
Yan Ni's avatar
Yan Ni committed
226
227
228
229

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
Yuge Zhang's avatar
Yuge Zhang committed
230
html_theme = 'sphinx_material'
Yan Ni's avatar
Yan Ni committed
231
232
233
234
235
236

# 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.
#
html_theme_options = {
Yuge Zhang's avatar
Yuge Zhang committed
237
238
239
240
241
242
243
244
245
246
247
248
249

    # Set the name of the project to appear in the navigation.
    'nav_title': 'Neural Network Intelligence',

    # Set you GA account ID to enable tracking
    'google_analytics_account': 'UA-136029994-1',

    # Specify a base_url used to generate sitemap.xml. If not
    # specified, then no sitemap will be built.
    'base_url': 'https://nni.readthedocs.io/',

    # Set the color and the accent color
    # Remember to update static/css/material_custom.css when this is updated.
Yuge Zhang's avatar
Yuge Zhang committed
250
251
252
    # Set those colors in layout.html.
    'color_primary': 'custom',
    'color_accent': 'custom',
Yuge Zhang's avatar
Yuge Zhang committed
253
254
255

    # Set the repo location to get a badge with stats
    'repo_url': 'https://github.com/microsoft/nni/',
Yuge Zhang's avatar
Yuge Zhang committed
256
    'repo_name': 'GitHub',
Yuge Zhang's avatar
Yuge Zhang committed
257
258

    # Visible levels of the global TOC; -1 means unlimited
259
260
261
262
    'globaltoc_depth': 5,

    # Expand all toc so that they can be dynamically collapsed
    'globaltoc_collapse': False,
Yuge Zhang's avatar
Yuge Zhang committed
263
264
265
266
267
268
269
270
271

    'version_dropdown': True,
    # This is a placeholder, which should be replaced later.
    'version_info': {
        'current': '/'
    },

    # Text to appear at the top of the home page in a "hero" div.
    'heroes': {
Yuge Zhang's avatar
Yuge Zhang committed
272
273
        'index': 'An open source AutoML toolkit for hyperparameter optimization, neural architecture search, '
                 'model compression and feature engineering.'
Yuge Zhang's avatar
Yuge Zhang committed
274
    }
Yan Ni's avatar
Yan Ni committed
275
276
}

Yuge Zhang's avatar
Yuge Zhang committed
277
278
279
# Disable show source link.
html_show_sourcelink = False

Yan Ni's avatar
Yan Ni committed
280
281
282
# 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".
Guoxin's avatar
Guoxin committed
283
html_static_path = ['../static']
Yan Ni's avatar
Yan Ni committed
284
285
286
287
288
289
290
291
292

# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself.  Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
Yuge Zhang's avatar
Yuge Zhang committed
293
294
295
html_sidebars = {
    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
}
Yan Ni's avatar
Yan Ni committed
296

Yuge Zhang's avatar
Yuge Zhang committed
297
298
299
300
html_title = 'Neural Network Intelligence'

# Add extra css files and js files
html_css_files = [
Yuge Zhang's avatar
Yuge Zhang committed
301
    'css/material_theme.css',
Yuge Zhang's avatar
Yuge Zhang committed
302
303
    'css/material_custom.css',
    'css/material_dropdown.css',
304
    'css/sphinx_gallery.css',
Yuge Zhang's avatar
Yuge Zhang committed
305
306
307
308
309
    'css/index_page.css',
]
html_js_files = [
    'js/version.js',
    'js/github.js',
310
    'js/sphinx_gallery.js',
Yuge Zhang's avatar
Yuge Zhang committed
311
    'js/misc.js'
Yuge Zhang's avatar
Yuge Zhang committed
312
]
Yan Ni's avatar
Yan Ni committed
313

314
315
316
317
318
319
320
# HTML context that can be used in jinja templates
git_commit_id = subprocess.check_output(['git', 'rev-parse', 'HEAD']).decode().strip()

html_context = {
    'git_commit_id': git_commit_id
}

Yan Ni's avatar
Yan Ni committed
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
# -- Options for HTMLHelp output ---------------------------------------------

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


# -- Options for LaTeX output ------------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    # 'preamble': '',

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (master_doc, 'NeuralNetworkIntelligence.tex', 'Neural Network Intelligence Documentation',
     'Microsoft', 'manual'),
]


# -- Options for manual page output ------------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (master_doc, 'neuralnetworkintelligence', 'Neural Network Intelligence Documentation',
     [author], 1)
]


# -- Options for Texinfo output ----------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (master_doc, 'NeuralNetworkIntelligence', 'Neural Network Intelligence Documentation',
     author, 'NeuralNetworkIntelligence', 'One line description of project.',
     'Miscellaneous'),
]


# -- Options for Epub output -------------------------------------------------

# Bibliographic Dublin Core info.
epub_title = project

# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''

# A unique identification for the text.
#
# epub_uid = ''

# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']

395
396
397
398
399
# external links (for github code)
# Reference the code via :githublink:`path/to/your/example/code.py`
extlinks = {
    'githublink': ('https://github.com/microsoft/nni/blob/' + git_commit_id + '/%s', 'Github link: ')
}