"vscode:/vscode.git/clone" did not exist on "7a80f56513752e2ed63beed542daaf28119cd89a"
conf.py 11.9 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.
#
20
21
import os
import re
moto's avatar
moto committed
22
import sys
23
import warnings
moto's avatar
moto committed
24
from datetime import datetime
25

moto's avatar
moto committed
26
27
sys.path.insert(0, os.path.abspath("."))

moto's avatar
moto committed
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.
#
moto's avatar
moto committed
38
needs_sphinx = "4.0.0"
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",
moto's avatar
moto committed
56
    "breathe",
57
58
]

moto's avatar
moto committed
59
60
61
62
63
64
65
66
67
68
69
breathe_projects = {"libtorchaudio": "cpp/xml"}

breathe_default_project = "libtorchaudio"

breathe_projects_source = {
    "libtorchaudio": (
        "../../torchaudio/csrc/ffmpeg/",
        ["ffmpeg.h"],
    )
}

moto's avatar
moto committed
70
71
nbsphinx_requirejs_path = ""

moto's avatar
moto committed
72
73
autodoc_member_order = "bysource"

74
75
76
77
# katex options
#
#

78
katex_options = r"""
79
80
81
82
83
delimiters : [
   {left: "$$", right: "$$", display: true},
   {left: "\\(", right: "\\)", display: false},
   {left: "\\[", right: "\\]", display: true}
]
84
"""
85

86
bibtex_bibfiles = ["refs.bib"]
87
bibtex_reference_style = "author_year"
moto's avatar
moto committed
88

89
90
91
92
93

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

94
95
96
    val = os.environ.get(var, "0")
    trues = ["1", "true", "TRUE", "on", "ON", "yes", "YES"]
    falses = ["0", "false", "FALSE", "off", "OFF", "no", "NO"]
97
98
99
100
    if val in trues:
        return True
    if val not in falses:
        print(
101
102
            f" --- WARNING: Unexpected environment variable value `{var}={val}`. " f"Expected one of {trues + falses}"
        )
103
104
105
106
    return False


def _get_pattern():
107
    pattern = os.getenv("GALLERY_PATTERN")
108
109
110
111
112
    # 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
113
    if not _get_var("BUILD_GALLERY", default=False if pattern is None else True):
114
115
116
        if pattern is not None:
            print(
                ' --- WARNING: "GALLERY_PATTERN" is provided, but "BUILD_GALLERY" value is falsy. '
117
                "Sphinx galleries are not built. To build galleries, set `BUILD_GALLERY=1`."
118
119
            )
        return {
120
            "ignore_pattern": r"\.py",
121
122
        }

123
124
    ret = {"filename_pattern": "tutorial.py"}
    if os.getenv("GALLERY_PATTERN"):
125
        # See https://github.com/pytorch/tutorials/blob/cbf2238df0e78d84c15bd94288966d2f4b2e83ae/conf.py#L75-L83
126
        ret["ignore_pattern"] = r"/(?!" + re.escape(os.getenv("GALLERY_PATTERN")) + r")[^/]+$"
127
128
129
    return ret


moto's avatar
moto committed
130
sphinx_gallery_conf = {
131
132
    "examples_dirs": [
        "../../examples/tutorials",
moto's avatar
moto committed
133
    ],
134
135
    "gallery_dirs": [
        "tutorials",
moto's avatar
moto committed
136
    ],
137
    **_get_pattern(),
138
    "backreferences_dir": "gen_modules/backreferences",
moto's avatar
moto committed
139
    "promote_jupyter_magic": True,
140
141
    "first_notebook_cell": None,
    "doc_module": ("torchaudio",),
moto's avatar
moto committed
142
143
144
}
autosummary_generate = True

145
napoleon_use_ivar = True
146
147
napoleon_numpy_docstring = False
napoleon_google_docstring = True
148
149

# Add any paths that contain templates here, relative to this directory.
150
templates_path = ["_templates"]
151
152
153
154
155

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

# The master toctree document.
159
master_doc = "index"
160
161

# General information about the project.
162
project = "Torchaudio"
moto's avatar
moto committed
163
copyright = f"{datetime.now().year}, Torchaudio Contributors"
164
author = "Torchaudio Contributors"
165
166
167
168
169

# 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
170
171
172
173
174
175
176
177
178
# `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"
179

180
181
182
183
184
185
186
187
188

#
# Specify the version of the current stable release.
# Used in `docs/source/_templates/breadcrumbs.html`
#
# https://stackoverflow.com/a/33845358/1106930
#
html_context = {"version_stable": "2.0.1"}

189
190
191
# 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
192
193
194
195
196
197
exclude_patterns = [
    "*/index.rst",
    "tutorials/*.md5",
    "tutorials/*.py",
    "tutorials/*.ipynb",
]
198
199

# The name of the Pygments (syntax highlighting) style to use.
200
pygments_style = "sphinx"
201
202
203
204
205
206
207
208
209
210

# 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.
#
211
html_theme = "pytorch_sphinx_theme"
212
html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()]
213

moto's avatar
moto committed
214
215
html_favicon = "_static/img/favicon.ico"

216
217
218
219
220
# 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 = {
221
222
223
224
225
226
    "pytorch_project": "audio",
    "collapse_navigation": False,
    "display_version": True,
    "logo_only": True,
    "navigation_with_keys": True,
    "analytics_id": "UA-117752657-2",
227
228
229
230
231
}

# 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".
232
html_static_path = ["_static"]
233
html_css_files = ["https://cdn.jsdelivr.net/npm/katex@0.10.0-beta/dist/katex.min.css", "css/custom.css"]
234
235
236
237

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

# Output file base name for HTML help builder.
238
htmlhelp_basename = "TorchAudiodoc"
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261


# -- 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 = [
262
    (master_doc, "pytorch.tex", "Torchaudio Documentation", "Torch Contributors", "manual"),
263
264
265
266
267
268
269
]


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

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
270
man_pages = [(master_doc, "Torchaudio", "Torchaudio Documentation", [author], 1)]
271
272
273
274
275
276
277
278


# -- 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 = [
279
280
281
282
283
284
285
286
287
    (
        master_doc,
        "Torchaudio",
        "Torchaudio Documentation",
        author,
        "Torchaudio",
        "Load audio files into pytorch tensors.",
        "Miscellaneous",
    ),
288
289
290
291
292
]


# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
293
294
295
    "python": ("https://docs.python.org/3/", None),
    "numpy": ("https://numpy.org/doc/stable/", None),
    "torch": ("https://pytorch.org/docs/stable/", None),
296
297
298
299
300
301
302
}

# -- 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
303
from sphinx.util.docfields import TypedField
304
305
306
307
308
309


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
310
    # type: (list, str, tuple) -> nodes.field
311
312
    def handle_item(fieldarg, content):
        par = nodes.paragraph()
313
        par += addnodes.literal_strong("", fieldarg)  # Patch: this line added
314
315
316
        # par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
        #                           addnodes.literal_strong))
        if fieldarg in types:
317
            par += nodes.Text(" (")
318
319
320
321
322
            # 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):
323
324
325
326
327
328
                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))
329
330
            else:
                par += fieldtype
331
332
            par += nodes.Text(")")
        par += nodes.Text(" -- ")
333
334
335
        par += content
        return par

336
    fieldname = nodes.field_name("", self.label)
337
338
339
340
341
342
    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:
343
344
345
346
            bodynode += nodes.list_item("", handle_item(fieldarg, content))
    fieldbody = nodes.field_body("", bodynode)
    return nodes.field("", fieldname, fieldbody)

347
348

TypedField.make_field = patched_make_field
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369


# 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")


def setup(app):
    app.connect("autodoc-process-docstring", inject_minigalleries)
moto's avatar
moto committed
370
371


moto's avatar
moto committed
372
from custom_directives import CustomCardEnd, CustomCardItem, CustomCardStart, SupportedDevices, SupportedProperties
moto's avatar
moto committed
373
374
375
376
377
378
379

# Register custom directives

from docutils.parsers import rst

rst.directives.register_directive("devices", SupportedDevices)
rst.directives.register_directive("properties", SupportedProperties)
moto's avatar
moto committed
380
381
382
rst.directives.register_directive("customcardstart", CustomCardStart)
rst.directives.register_directive("customcarditem", CustomCardItem)
rst.directives.register_directive("customcardend", CustomCardEnd)