#!/usr/bin/env python3

# -*- coding: utf-8 -*-

#

# PyTorch Tutorials documentation build configuration file, created by

# sphinx-quickstart on Wed Mar 8 22:38:10 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.

#

# Because the sphinx gallery might take a long time, you can control specific

# files that generate the results using `GALLERY_PATTERN` environment variable,

# For example to run only `neural_style_transfer_tutorial.py`:

# GALLERY_PATTERN="neural_style_transfer_tutorial.py" make html

# or

# GALLERY_PATTERN="neural_style_transfer_tutorial.py" sphinx-build . _build

#

# GALLERY_PATTERN variable respects regular expressions.

# 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.

#

import os

import sys

sys.path.insert(0, os.path.abspath("."))

sys.path.insert(0, os.path.abspath("./.jenkins"))

import pytorch_sphinx_theme2

html_theme = "pytorch_sphinx_theme2"

html_theme_path = [pytorch_sphinx_theme2.get_html_theme_path()]

import distutils.file_util

import glob

import random

import re

import shutil

from pathlib import Path

import pandocfilters

import plotly.io as pio

import pypandoc

import torch

from get_sphinx_filenames import SPHINX_SHOULD_RUN

pio.renderers.default = "sphinx_gallery"

import multiprocessing

import sphinx_gallery.gen_rst

from redirects import redirects

# Monkey patch sphinx gallery to run each example in an isolated process so that

# we don't need to worry about examples changing global state.

#

# Alt option 1: Parallelism was added to sphinx gallery (a later version that we

# are not using yet) using joblib, but it seems to result in errors for us, and

# it has no effect if you set parallel = 1 (it will not put each file run into

# its own process and run singly) so you need parallel >= 2, and there may be

# tutorials that cannot be run in parallel.

#

# Alt option 2: Run sphinx gallery once per file (similar to how we shard in CI

# but with shard sizes of 1), but running sphinx gallery for each file has a

# ~5min overhead, resulting in the entire suite taking ~2x time

def call_fn(func, args, kwargs, result_queue):

try:

result = func(*args, **kwargs)

result_queue.put((True, result))

except Exception as e:

result_queue.put((False, str(e)))

def call_in_subprocess(func):

def wrapper(*args, **kwargs):

result_queue = multiprocessing.Queue()

p = multiprocessing.Process(

target=call_fn, args=(func, args, kwargs, result_queue)

)

p.start()

p.join()

success, result = result_queue.get()

if success:

return result

else:

raise RuntimeError(f"Error in subprocess: {result}")

return wrapper

# Windows does not support multiprocessing with fork and mac has issues with

# fork so we do not monkey patch sphinx gallery to run in subprocesses.

if (

os.getenv("TUTORIALS_ISOLATE_BUILD", "1") == "1"

and not sys.platform.startswith("win")

and not sys.platform == "darwin"

):

sphinx_gallery.gen_rst.generate_file_rst = call_in_subprocess(

sphinx_gallery.gen_rst.generate_file_rst

)

try:

import torchvision

except ImportError:

import warnings

warnings.warn('unable to load "torchvision" package')

rst_epilog = """

.. |edit| image:: /_static/pencil-16.png

:width: 16px

:height: 16px

"""

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

# If your documentation needs a minimal Sphinx version, state it here.

#

# needs_sphinx = '1.0'

html_meta = {

"description": "Master PyTorch with our step-by-step tutorials for all skill levels. Start your journey to becoming a PyTorch expert today!",

"keywords": "PyTorch, tutorials, Getting Started, deep learning, AI",

"author": "PyTorch Contributors",

}

# Add any Sphinx extension module names here, as strings. They can be

# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

# ones.

extensions = [

"sphinxcontrib.katex",

"sphinx.ext.intersphinx",

"sphinx_copybutton",

"sphinx_gallery.gen_gallery",

"sphinx_design",

"sphinx_sitemap",

"sphinx_reredirects",

"sphinxcontrib.mermaid",

]

intersphinx_mapping = {

"torch": ("https://docs.pytorch.org/docs/stable/", None),

"tensordict": ("https://docs.pytorch.org/tensordict/stable", None),

"torchrl": ("https://docs.pytorch.org/rl/stable", None),

"torchaudio": ("https://docs.pytorch.org/audio/stable/", None),

"torchtext": ("https://docs.pytorch.org/text/stable/", None),

"torchvision": ("https://docs.pytorch.org/vision/stable/", None),

}

html_meta = {

"description": "Master PyTorch with our step-by-step tutorials for all skill levels. Start your journey to becoming a PyTorch expert today!",

"keywords": "PyTorch, tutorials, Getting Started, deep learning, AI",

"author": "PyTorch Contributors",

}

# -- Sphinx-gallery configuration --------------------------------------------

sphinx_gallery_conf = {

"examples_dirs": [

"beginner_source",

"intermediate_source",

"advanced_source",

"recipes_source",

"unstable_source",

],

"gallery_dirs": ["beginner", "intermediate", "advanced", "recipes", "unstable"],

"filename_pattern": re.compile(SPHINX_SHOULD_RUN),

"promote_jupyter_magic": True,

"backreferences_dir": None,

"write_computation_times": True,

"download_all_examples": False,

"show_signature": False,

"first_notebook_cell": (

"# For tips on running notebooks in Google Colab, see\n"

"# https://docs.pytorch.org/tutorials/beginner/colab\n"

"%matplotlib inline"

),

"ignore_pattern": r"_torch_export_nightly_tutorial.py",

"pypandoc": {

"extra_args": ["--mathjax", "--toc"],

"filters": [".jenkins/custom_pandoc_filter.py"],

},

}

html_additional_pages = {

"404": "404.html",

}

html_baseurl = "https://docs.pytorch.org/tutorials/" # needed for sphinx-sitemap

sitemap_locales = [None]

sitemap_excludes = [

"search.html",

"genindex.html",

]

sitemap_url_scheme = "{link}"

html_theme_options = {

"navigation_with_keys": False,

"analytics_id": "GTM-T8XT4PS",

"logo": {

"text": "",

},

"icon_links": [

{

"name": "X",

"url": "https://x.com/PyTorch",

"icon": "fa-brands fa-x-twitter",

},

{

"name": "GitHub",

"url": "https://github.com/pytorch/tutorials",

"icon": "fa-brands fa-github",

},

{

"name": "Discourse",

"url": "https://dev-discuss.pytorch.org/",

"icon": "fa-brands fa-discourse",

},

{

"name": "PyPi",

"url": "https://pypi.org/project/torch/",

"icon": "fa-brands fa-python",

},

],

"use_edit_page_button": True,

"header_links_before_dropdown": 9,

"navbar_start": ["pytorch_version"],

"navbar_center": "navbar-nav",

"display_version": True,

"pytorch_project": "tutorials",

"canonical_url": "https://docs.pytorch.org/tutorials/",

}

theme_variables = pytorch_sphinx_theme2.get_theme_variables()

html_context = {

"theme_variables": theme_variables,

"display_github": True,

"github_url": "https://github.com",

"github_user": "pytorch",

"github_repo": "tutorials",

"feedback_url": "https://github.com/pytorch/tutorials",

"github_version": "main",

"doc_path": ".",

"library_links": theme_variables.get("library_links", []),

#"pytorch_project": "tutorials",

}

if os.getenv("GALLERY_PATTERN"):

# GALLERY_PATTERN is to be used when you want to work on a single

# tutorial. Previously this was fed into filename_pattern, but

# if you do that, you still end up parsing all of the other Python

# files which takes a few seconds. This strategy is better, as

# ignore_pattern also skips parsing.

# See https://github.com/sphinx-gallery/sphinx-gallery/issues/721

# for a more detailed description of the issue.

sphinx_gallery_conf["ignore_pattern"] = (

r"/(?!" + re.escape(os.getenv("GALLERY_PATTERN")) + r")[^/]+$"

)

for i in range(len(sphinx_gallery_conf["examples_dirs"])):

gallery_dir = Path(sphinx_gallery_conf["gallery_dirs"][i])

source_dir = Path(sphinx_gallery_conf["examples_dirs"][i])

# Copy rst files from source dir to gallery dir

for f in source_dir.rglob("*.rst"):

f_dir = Path(f).parent

gallery_subdir_path = gallery_dir / f_dir.relative_to(source_dir)

gallery_subdir_path.mkdir(parents=True, exist_ok=True)

distutils.file_util.copy_file(f, gallery_subdir_path, update=True)

# Add any paths that contain templates here, relative to this directory.

templates_path = [

"_templates",

os.path.join(os.path.dirname(pytorch_sphinx_theme2.__file__), "templates"),

]

# The suffix(es) of source filenames.

# You can specify multiple suffix as a list of string:

#

# source_suffix = ['.rst', '.md']

source_suffix = ".rst"

# The master toctree document.

master_doc = "index"

# General information about the project.

project = "PyTorch Tutorials"

copyright = "2024, PyTorch"

author = "PyTorch contributors"

# 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.

#

# The short X.Y version.

version = "v" + str(torch.__version__)

# The full version, including alpha/beta/rc tags.

release = str(torch.__version__)

# 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 = "en"

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

"src/pytorch-sphinx-theme/docs*",

]

exclude_patterns += sphinx_gallery_conf["examples_dirs"]

exclude_patterns += ["*/index.rst"]

# Handling for HuggingFace Hub jinja templates

def handle_jinja_templates(app, docname, source):

if "huggingface_hub/templates" in docname:

# Replace Jinja templates with quoted strings

source[0] = re.sub(r"(\{\{.*?\}\})", r'"\1"', source[0])

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

pygments_style = "sphinx"

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

todo_include_todos = False

# -- 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 = 'alabaster'

# # 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 = {

# 'page_width': '1000px',

# 'fixed_sidebar': True,

# 'code_font_size': '0.87em',

# 'sidebar_includehidden': True

# }

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

# # Custom sidebar templates, maps document names to template names.

# html_sidebars = {

# 'index': ['sidebarlogo.html', 'globaltoc.html', 'searchbox.html', 'sourcelink.html'],

# '**': ['sidebarlogo.html', 'globaltoc.html', 'searchbox.html', 'sourcelink.html']

# }

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

# Output file base name for HTML help builder.

htmlhelp_basename = "PyTorchTutorialsdoc"

# -- 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,

"PyTorchTutorials.tex",

"PyTorch Tutorials",

"Sasank, PyTorch contributors",

"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, "pytorchtutorials", "PyTorch Tutorials", [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,

"PyTorchTutorials",

"PyTorch Tutorials",

author,

"PyTorchTutorials",

"One line description of project.",

"Miscellaneous",

),

]

html_css_files = [

"https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css",

]

def html_page_context(app, pagename, templatename, context, doctree):

# Check if the page is in gallery directories

for gallery_dir in sphinx_gallery_conf["gallery_dirs"]:

if pagename.startswith(gallery_dir):

# Get corresponding examples directory

examples_dir = sphinx_gallery_conf["examples_dirs"][

sphinx_gallery_conf["gallery_dirs"].index(gallery_dir)

]

# Calculate relative path within the gallery

rel_path = (

pagename[len(gallery_dir) + 1 :] if pagename != gallery_dir else ""

)

# Check for .py file in examples directory

py_path = os.path.join(app.srcdir, examples_dir, rel_path + ".py")

# If a .py file exists, this page was generated from Python

if os.path.exists(py_path):

context["display_github"] = False

return

# Enable for all other pages

context["display_github"] = True

def setup(app):

app.connect("source-read", handle_jinja_templates)

app.connect("html-page-context", html_page_context)