# # 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. # # NB: C++ API doc generation using doxygen / breathe / exhale is currently only # enabled on nightlies (and not trunk or on PRs) due to OOM errors in CI. # See https://github.com/pytorch/pytorch/issues/79992. import os import textwrap # sys.path.insert(0, os.path.abspath('.')) import pytorch_sphinx_theme2 # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = "3.1.2" run_doxygen = os.environ.get("RUN_DOXYGEN", "false") == "true" # 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.intersphinx", ] + (["breathe", "exhale"] if run_doxygen else []) intersphinx_mapping = {"pytorch": ("https://docs.pytorch.org/docs/main", None)} # Configure Sphinx warnings and error handling suppress_warnings = [ "ref.citation", "ref.footnote", "ref.doc", "toc.excluded", "toc.not_readable", "misc.highlighting_failure", ] # Configure Breathe breathe_show_define_initializer = True breathe_show_enumvalue_initializer = True breathe_default_members = ("members", "undoc-members") # Fix for Python 3.10+ compatibility with exhale 2.3.0 # MutableMapping was moved from collections to collections.abc in Python 3.10 try: import collections from collections.abc import MutableMapping if not hasattr(collections, "MutableMapping"): collections.MutableMapping = MutableMapping except ImportError: pass # Setup absolute paths for communicating with breathe / exhale where # items are expected / should be trimmed by. # This file is {repo_root}/docs/cpp/source/conf.py this_file_dir = os.path.abspath(os.path.dirname(__file__)) doxygen_xml_dir = os.path.join( os.path.dirname(this_file_dir), # {repo_root}/docs/cpp "build", # {repo_root}/docs/cpp/build "xml", # {repo_root}/docs/cpp/build/xml ) repo_root = os.path.dirname( # {repo_root} os.path.dirname( # {repo_root}/docs os.path.dirname( # {repo_root}/docs/cpp this_file_dir # {repo_root}/docs/cpp/source ) ) ) breathe_projects = {"PyTorch": doxygen_xml_dir} breathe_default_project = "PyTorch" # Setup the exhale extension exhale_args = { ############################################################################ # These arguments are required. # ############################################################################ "containmentFolder": "./api", "rootFileName": "library_root.rst", "rootFileTitle": "Library API", "doxygenStripFromPath": repo_root, ############################################################################ # Suggested optional arguments. # ############################################################################ "createTreeView": True, "exhaleExecutesDoxygen": True, "exhaleUseDoxyfile": True, "verboseBuild": True, ############################################################################ # HTML Theme specific configurations. # ############################################################################ # Fix broken Sphinx RTD Theme 'Edit on GitHub' links # Search for 'Edit on GitHub' on the FAQ: # http://exhale.readthedocs.io/en/latest/faq.html "pageLevelConfigMeta": ":github_url: https://github.com/pytorch/pytorch", ############################################################################ # Individual page layout example configuration. # ############################################################################ # Example of adding contents directives on custom kinds with custom title "contentsTitle": "Page Contents", "kindsWithContentsDirectives": ["class", "file", "namespace", "struct"], # Exclude PIMPL files from class hierarchy tree and namespace pages. "listingExclude": [r".*Impl$"], ############################################################################ # Main library page layout example configuration. # ############################################################################ "afterTitleDescription": textwrap.dedent( """ Welcome to the developer reference for the PyTorch C++ API. """ ), ############################################################################ # Duplicate handling and error management. # ############################################################################ # Note: Using Doxyfile instead of stdin configuration # "exhaleDoxygenStdin" is not compatible with "exhaleUseDoxyfile" # Handle unresolved references more gracefully "unabridgedOrphanKinds": { "function", "define", "enum", "enumvalue", "typedef", "variable", }, "fullToctreeMaxDepth": 2, } # Tell sphinx what the primary language being documented is. primary_domain = "cpp" # Tell sphinx what the pygments highlight language should be. highlight_language = "cpp" # Add any paths that contain templates here, relative to this directory. # templates_path = ['_templates'] theme_variables = pytorch_sphinx_theme2.get_theme_variables() 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" copyright = "PyTorch Contributors" 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. # TODO: change to [:2] at v1.0 version = "main" # The full version, including alpha/beta/rc tags. # TODO: verify this works as expected release = "main" # 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 = [] # 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 = True # -- 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 = "pytorch_sphinx_theme2" # 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 = { "canonical_url": "https://pytorch.org/docs/stable/", "analytics_id": "GTM-T8XT4PS", "collapse_navigation": False, "logo": {"text": "Home"}, "icon_links": [ { "name": "X", "url": "https://x.com/PyTorch", "icon": "fa-brands fa-x-twitter", }, { "name": "GitHub", "url": "https://github.com/pytorch/pytorch", "icon": "fa-brands fa-github", }, { "name": "PyTorch Forum", "url": "https://discuss.pytorch.org/", "icon": "fa-brands fa-discourse", }, { "name": "PyPi", "url": "https://pypi.org/project/torch/", "icon": "fa-brands fa-python", }, ], "navbar_start": ["pytorch_version"], "display_version": True, } html_context = { "theme_variables": theme_variables, "github_url": "https://github.com", "github_user": "pytorch", "github_repo": "pytorch", "feedback_url": "https://github.com/pytorch/pytorch", "github_version": "main", "doc_path": "docs/cpp/source", "library_links": theme_variables.get("library_links", []), "community_links": theme_variables.get("community_links", []), "language_bindings_links": theme_variables.get("language_bindings_links", []), } # NOTE: sharing python docs resources # 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". # NOTE: sharing python docs resources html_static_path = [os.path.join(repo_root, "docs", "cpp", "source", "_static")] html_css_files = ["cpp_theme.css"] # Called automatically by Sphinx, making this `conf.py` an "extension". # -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. # htmlhelp_basename = 'PyTorchdoc' # -- 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, "pytorch.tex", "PyTorch Documentation", "Torch 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, "PyTorch", "PyTorch 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, "PyTorch", "PyTorch Documentation", author, "PyTorch", "One line description of project.", "Miscellaneous", ), ]