conf.py 12.5 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# PyTorch documentation build configuration file, created by
# sphinx-quickstart on Fri Dec 23 13:31:47 2016.
#
# 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
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
moto's avatar
moto committed
20
import importlib
21
import os
moto's avatar
moto committed
22
23
24
import sys

sys.path.insert(0, os.path.abspath("."))
25
import re
26
import warnings
moto's avatar
moto committed
27
from datetime import datetime
28

29
import pytorch_sphinx_theme
30
31
32

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

33
warnings.filterwarnings("ignore", module=r"matplotlib\..*")
34
35


36
37
# If your documentation needs a minimal Sphinx version, state it here.
#
38
needs_sphinx = "1.6"
39
40
41
42
43

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
44
45
46
47
48
49
50
51
52
53
54
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.doctest",
    "sphinx.ext.intersphinx",
    "sphinx.ext.todo",
    "sphinx.ext.coverage",
    "sphinx.ext.napoleon",
    "sphinx.ext.viewcode",
    "sphinxcontrib.katex",
    "sphinxcontrib.bibtex",
    "sphinx_gallery.gen_gallery",
55
    "nbsphinx",
56
57
]

moto's avatar
moto committed
58
59
nbsphinx_requirejs_path = ""

moto's avatar
moto committed
60
61
autodoc_member_order = "bysource"

62
63
64
65
# katex options
#
#

66
katex_options = r"""
67
68
69
70
71
delimiters : [
   {left: "$$", right: "$$", display: true},
   {left: "\\(", right: "\\)", display: false},
   {left: "\\[", right: "\\]", display: true}
]
72
"""
73

74
bibtex_bibfiles = ["refs.bib"]
75
bibtex_reference_style = "author_year"
moto's avatar
moto committed
76

77
78
79
80
81

def _get_var(var, default=False):
    if var not in os.environ:
        return default

82
83
84
    val = os.environ.get(var, "0")
    trues = ["1", "true", "TRUE", "on", "ON", "yes", "YES"]
    falses = ["0", "false", "FALSE", "off", "OFF", "no", "NO"]
85
86
87
88
    if val in trues:
        return True
    if val not in falses:
        print(
89
90
            f" --- WARNING: Unexpected environment variable value `{var}={val}`. " f"Expected one of {trues + falses}"
        )
91
92
93
94
    return False


def _get_pattern():
95
    pattern = os.getenv("GALLERY_PATTERN")
96
97
98
99
100
    # If BUILD_GALLERY is falsy -> no build
    # If BUILD_GALLERY is truey -> build
    # If BUILD_GALLERY is undefined
    #    If GALLERY_PATTERN is defined     -> build
    #    If GALLERY_PATTERN is not defined -> not build
101
    if not _get_var("BUILD_GALLERY", default=False if pattern is None else True):
102
103
104
        if pattern is not None:
            print(
                ' --- WARNING: "GALLERY_PATTERN" is provided, but "BUILD_GALLERY" value is falsy. '
105
                "Sphinx galleries are not built. To build galleries, set `BUILD_GALLERY=1`."
106
107
            )
        return {
108
            "ignore_pattern": r"\.py",
109
110
        }

111
112
    ret = {"filename_pattern": "tutorial.py"}
    if os.getenv("GALLERY_PATTERN"):
113
        # See https://github.com/pytorch/tutorials/blob/cbf2238df0e78d84c15bd94288966d2f4b2e83ae/conf.py#L75-L83
114
        ret["ignore_pattern"] = r"/(?!" + re.escape(os.getenv("GALLERY_PATTERN")) + r")[^/]+$"
115
116
117
    return ret


moto's avatar
moto committed
118
sphinx_gallery_conf = {
119
120
    "examples_dirs": [
        "../../examples/tutorials",
moto's avatar
moto committed
121
    ],
122
123
    "gallery_dirs": [
        "tutorials",
moto's avatar
moto committed
124
    ],
125
    **_get_pattern(),
126
127
128
    "backreferences_dir": "gen_modules/backreferences",
    "first_notebook_cell": None,
    "doc_module": ("torchaudio",),
moto's avatar
moto committed
129
130
131
}
autosummary_generate = True

132
napoleon_use_ivar = True
133
134
napoleon_numpy_docstring = False
napoleon_google_docstring = True
135
136

# Add any paths that contain templates here, relative to this directory.
137
templates_path = ["_templates"]
138
139
140
141
142

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
143
source_suffix = ".rst"
144
145

# The master toctree document.
146
master_doc = "index"
147
148

# General information about the project.
149
project = "Torchaudio"
moto's avatar
moto committed
150
copyright = f"{datetime.now().year}, Torchaudio Contributors"
151
author = "Torchaudio Contributors"
152
153
154
155
156

# 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.
#
moto's avatar
moto committed
157
158
159
160
161
162
163
164
165
# `version` is visible from users
# `release` is used for metadata
if os.getenv("BUILD_VERSION"):
    version = release = os.environ["BUILD_VERSION"]
else:
    import torchaudio

    version = f"Nightly Build ({torchaudio.__version__})"
    release = "nightly"
166
167
168
169
170
171
172
173
174
175
176

# 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

# 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
177
178
179
180
181
182
exclude_patterns = [
    "*/index.rst",
    "tutorials/*.md5",
    "tutorials/*.py",
    "tutorials/*.ipynb",
]
183
184

# The name of the Pygments (syntax highlighting) style to use.
185
pygments_style = "sphinx"
186
187
188
189
190
191
192
193
194
195

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True


# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
196
html_theme = "pytorch_sphinx_theme"
197
html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()]
198
199
200
201
202
203

# 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 = {
204
205
206
207
208
209
    "pytorch_project": "audio",
    "collapse_navigation": False,
    "display_version": True,
    "logo_only": True,
    "navigation_with_keys": True,
    "analytics_id": "UA-117752657-2",
210
211
}

212
html_logo = "_static/img/pytorch-logo-dark.svg"
213
214
215
216

# 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".
217
html_static_path = ["_static"]
218
html_css_files = ["https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.css", "css/custom.css"]
219
220
221
222

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

# Output file base name for HTML help builder.
223
htmlhelp_basename = "TorchAudiodoc"
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246


# -- 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 = [
247
    (master_doc, "pytorch.tex", "Torchaudio Documentation", "Torch Contributors", "manual"),
248
249
250
251
252
253
254
]


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

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
255
man_pages = [(master_doc, "Torchaudio", "Torchaudio Documentation", [author], 1)]
256
257
258
259
260
261
262
263


# -- 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 = [
264
265
266
267
268
269
270
271
272
    (
        master_doc,
        "Torchaudio",
        "Torchaudio Documentation",
        author,
        "Torchaudio",
        "Load audio files into pytorch tensors.",
        "Miscellaneous",
    ),
273
274
275
276
277
]


# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
278
279
280
    "python": ("https://docs.python.org/3/", None),
    "numpy": ("https://numpy.org/doc/stable/", None),
    "torch": ("https://pytorch.org/docs/stable/", None),
281
282
283
284
285
286
287
}

# -- A patch that prevents Sphinx from cross-referencing ivar tags -------
# See http://stackoverflow.com/a/41184353/3343043

from docutils import nodes
from sphinx import addnodes
288
from sphinx.util.docfields import TypedField
289
290
291
292
293
294


def patched_make_field(self, types, domain, items, **kw):
    # `kw` catches `env=None` needed for newer sphinx while maintaining
    #  backwards compatibility when passed along further down!

Rahul Amaram's avatar
Rahul Amaram committed
295
    # type: (list, str, tuple) -> nodes.field
296
297
    def handle_item(fieldarg, content):
        par = nodes.paragraph()
298
        par += addnodes.literal_strong("", fieldarg)  # Patch: this line added
299
300
301
        # par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
        #                           addnodes.literal_strong))
        if fieldarg in types:
302
            par += nodes.Text(" (")
303
304
305
306
307
            # NOTE: using .pop() here to prevent a single type node to be
            # inserted twice into the doctree, which leads to
            # inconsistencies later when references are resolved
            fieldtype = types.pop(fieldarg)
            if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
308
309
310
311
312
313
                typename = "".join(n.astext() for n in fieldtype)
                typename = typename.replace("int", "python:int")
                typename = typename.replace("long", "python:long")
                typename = typename.replace("float", "python:float")
                typename = typename.replace("type", "python:type")
                par.extend(self.make_xrefs(self.typerolename, domain, typename, addnodes.literal_emphasis, **kw))
314
315
            else:
                par += fieldtype
316
317
            par += nodes.Text(")")
        par += nodes.Text(" -- ")
318
319
320
        par += content
        return par

321
    fieldname = nodes.field_name("", self.label)
322
323
324
325
326
327
    if len(items) == 1 and self.can_collapse:
        fieldarg, content = items[0]
        bodynode = handle_item(fieldarg, content)
    else:
        bodynode = self.list_type()
        for fieldarg, content in items:
328
329
330
331
            bodynode += nodes.list_item("", handle_item(fieldarg, content))
    fieldbody = nodes.field_body("", bodynode)
    return nodes.field("", fieldname, fieldbody)

332
333

TypedField.make_field = patched_make_field
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352


# Based off of
# https://github.com/sphinx-gallery/sphinx-gallery/blob/5b21962284f865beeaeb79cca50c8c394fa60cba/sphinx_gallery/directives.py#L66-L70
def _has_backref(obj):
    this_dir = os.path.dirname(__file__)
    path = os.path.join(this_dir, "gen_modules", "backreferences", f"{obj}.examples")
    return os.path.isfile(path) and os.path.getsize(path) > 0


# Based off of
# https://github.com/pytorch/vision/blob/5335006be7ef01c9f6cb700fe793d7c645e83e84/docs/source/conf.py#L262
def inject_minigalleries(app, what, name, obj, options, lines):
    if what in ("class", "function") and _has_backref(name):
        lines.append(f"Tutorials using ``{name.split('.')[-1]}``:")
        lines.append(f"    .. minigallery:: {name}")
        lines.append("\n")


moto's avatar
moto committed
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
# Overwrite the imported classes
def fix_module_path(module, attribute):
    attr = importlib.import_module(module)
    for attr_ in attribute:
        attr = getattr(attr, attr_)
    attr.__module__ = module


def fix_aliases():
    patterns = {
        "torchaudio.models": [
            ["HuBERTPretrainModel"],
            ["Wav2Vec2Model"],
            ["RNNT"],
            ["Tacotron2"],
        ],
        "torchaudio.pipelines": [
            ["Tacotron2TTSBundle"],
            ["Tacotron2TTSBundle", "TextProcessor"],
            ["Tacotron2TTSBundle", "Vocoder"],
        ],
    }
    for module, attributes in patterns.items():
        for attribute in attributes:
            fix_module_path(module, attribute)

    if importlib.util.find_spec("torchaudio.flashlight_lib_text_decoder") is not None:
Caroline Chen's avatar
Caroline Chen committed
380
381
382

        for class_ in ["CTCHypothesis", "CTCDecoderLM", "CTCDecoderLMState"]:
            fix_module_path("torchaudio.models.decoder", [class_])
moto's avatar
moto committed
383
384


385
def setup(app):
moto's avatar
moto committed
386
    fix_aliases()
387
    app.connect("autodoc-process-docstring", inject_minigalleries)
moto's avatar
moto committed
388
389
390
391
392
393
394
395
396
397


from custom_directives import SupportedDevices, SupportedProperties

# Register custom directives

from docutils.parsers import rst

rst.directives.register_directive("devices", SupportedDevices)
rst.directives.register_directive("properties", SupportedProperties)