diff --git a/.github/workflows/doc_build.yml b/.github/workflows/doc_build.yml new file mode 100644 index 000000000..0ccf556e0 --- /dev/null +++ b/.github/workflows/doc_build.yml @@ -0,0 +1,120 @@ +name: Build Docs + +on: + push: + branches: + - main + - release/* + tags: + - v[0-9]+.[0-9]+.[0-9] + - v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+ + pull_request: + workflow_dispatch: + +concurrency: + group: build-docs-${{ github.workflow }}-${{ github.ref == 'refs/heads/main' && github.run_number || github.ref }} + cancel-in-progress: true + +defaults: + run: + shell: bash -l -eo pipefail {0} + +jobs: + build_docs: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.11'] + steps: + - name: Check out repo + uses: actions/checkout@v3 + - name: Setup conda env + uses: conda-incubator/setup-miniconda@v2 + with: + auto-update-conda: true + miniconda-version: "latest" + activate-environment: test + python-version: ${{ matrix.python-version }} + - name: Update pip + run: python -m pip install --upgrade pip + - name: Install dependencies + run: | + python -m pip install torch + python -m pip install -e . + cd docs + python -m pip install -r requirements.txt + - name: Get the torchtune version + run: | + # Get the github.ref_name and save into the + # REF_NAME variable. This will be passed in + # conf.py to display the version in the + # site dropdown + REF_NAME=${{ github.ref_name }} + TORCHAO_VERSION_DOCS="${REF_NAME}" + echo "$TORCHAO_VERSION_DOCS" + - name: Build docs + run: | + cd docs + make html + - uses: actions/upload-artifact@v3 + with: + name: Doc-Build + path: docs/build/html/ + + upload: + runs-on: ubuntu-latest + permissions: + # Grant write permission here so that the doc can be pushed to gh-pages branch + contents: write + needs: build_docs + if: github.repository == 'pytorch-labs/ao' && github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/') || startsWith(github.ref, 'refs/tags/v')) + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: gh-pages + persist-credentials: false + - name: Download artifact + uses: actions/download-artifact@v3 + with: + name: Doc-Build + path: docs + - name: Add no-index tag + run: | + REF_NAME=$(echo "${{ github.ref }}") + echo "Ref name: ${REF_NAME}" + if [[ "${{ github.ref }}" == 'refs/heads/main' ]]; then + find docs -name "*.html" -print0 | xargs -0 sed -i '//a \ \ '; + fi + - name: Move and commit changes + env: + GITHUB_PYTORCHBOT_TOKEN: ${{ secrets.GH_PYTORCHBOT_TOKEN }} + run: | + git remote set-url origin https://pytorchbot:${GITHUB_PYTORCHBOT_TOKEN}@github.com/pytorch-labs/ao.git + set -euo pipefail + REF_TYPE=${{ github.ref_type }} + REF_NAME=${{ github.ref_name }} + if [[ "${REF_TYPE}" == branch ]]; then + TARGET_FOLDER="${REF_NAME}" + elif [[ "${REF_TYPE}" == tag ]]; then + case "${REF_NAME}" in + *-rc*) + echo "Aborting upload since this is an RC tag: ${REF_NAME}" + exit 0 + ;; + *) + TARGET_FOLDER=$(echo "${REF_NAME}" | sed 's/v\([0-9]\+\)\.\([0-9]\+\)\.[0-9]\+/\1.\2/') + ;; + esac + fi + + echo "Target Folder: ${TARGET_FOLDER}" + mkdir -p "${TARGET_FOLDER}" + rm -rf "${TARGET_FOLDER}"/* + mv docs/* "${TARGET_FOLDER}" + + git config user.name 'pytorchbot' + git config user.email 'soumith+bot@pytorch.org' + git add "${TARGET_FOLDER}" || true + git commit -m "auto-generating sphinx docs" || true + git push -f diff --git a/.gitignore b/.gitignore index 424cc4b76..8d56ff2b9 100644 --- a/.gitignore +++ b/.gitignore @@ -258,6 +258,10 @@ docs/gathered _site doxygen docs/dev +docs/build +docs/source/tutorials/* +docs/source/gen_modules/* +docs/source/sg_execution_times.rst # LevelDB files *.sst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..c5769c392 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,36 @@ +# Minimal makefile for Sphinx documentation +# + +ifneq ($(EXAMPLES_PATTERN),) + EXAMPLES_PATTERN_OPTS := -D sphinx_gallery_conf.filename_pattern="$(EXAMPLES_PATTERN)" +endif + +# You can set these variables from the command line. +SPHINXOPTS = -W -j auto $(EXAMPLES_PATTERN_OPTS) +SPHINXBUILD = sphinx-build +SPHINXPROJ = torchao +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +html-noplot: # Avoids running the gallery examples, which may take time + $(SPHINXBUILD) -D plot_gallery=0 -b html "${SOURCEDIR}" "$(BUILDDIR)"/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +clean: + rm -rf $(BUILDDIR)/* + rm -rf $(SOURCEDIR)/generated_examples/ # sphinx-gallery + rm -rf $(SOURCEDIR)/gen_modules/ # sphinx-gallery + rm -rf $(SOURCEDIR)/sg_execution_times.rst # sphinx-gallery + rm -rf $(SOURCEDIR)/generated/ # autosummary + +.PHONY: help Makefile docset + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.txt b/docs/README.txt new file mode 100644 index 000000000..013a8bc1b --- /dev/null +++ b/docs/README.txt @@ -0,0 +1,6 @@ +Tutorials +========= + +template_tutorial.py + Template Tutorial + tutorials/template_tutorial.html diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..99c41798e --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +sphinx-gallery>0.11 +sphinx==5.0.0 +sphinx_design +sphinx_copybutton +sphinx-tabs +matplotlib +-e git+https://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css new file mode 100644 index 000000000..dc81626f8 --- /dev/null +++ b/docs/source/_static/css/custom.css @@ -0,0 +1,187 @@ +/** + * Copyright (c) Meta Platforms, Inc. and affiliates. + * All rights reserved. + * + * This source code is licensed under the BSD-style license found in the + * LICENSE file in the root directory of this source tree. + */ + +/* sphinx-design styles for cards/tabs */ + + +:root { + --sd-color-info: #ee4c2c; + --sd-color-primary: #6c6c6d; + --sd-color-primary-highlight: #f3f4f7; + --sd-color-card-border-hover: #ee4c2c; + --sd-color-card-border: #f3f4f7; + --sd-color-card-background: #fff; + --sd-color-card-text: inherit; + --sd-color-card-header: transparent; + --sd-color-card-footer: transparent; + --sd-color-tabs-label-active: #ee4c2c; + --sd-color-tabs-label-hover: #ee4c2c; + --sd-color-tabs-label-inactive: #6c6c6d; + --sd-color-tabs-underline-active: #ee4c2c; + --sd-color-tabs-underline-hover: #fabdbd; + --sd-color-tabs-underline-inactive: transparent; + --sd-color-tabs-overline: rgb(222, 222, 222); + --sd-color-tabs-underline: rgb(222, 222, 222); +} + +.sd-text-info { + color: #ee4c2c; +} + +.sd-card-img-top { + background: #ee4c2c; + height: 5px !important; +} + +.sd-card { + position: relative; + background-color: #fff; + opacity: 1.0; + border-radius: 0px; + width: 30%; + border: none; + padding-bottom: 0px; +} + + +.sd-card-img:hover { + opacity: 1.0; + background-color: #f3f4f7; +} + + +.sd-card:after { + display: block; + opacity: 1; + content: ''; + border-bottom: solid 1px #ee4c2c; + background-color: #fff; + transform: scaleX(0); + transition: transform .250s ease-in-out; + transform-origin: 0% 50%; +} + +.sd-card:hover { + background-color: #fff; + opacity: 1; + border-top: 1px solid #f3f4f7; + border-left: 1px solid #f3f4f7; + border-right: 1px solid #f3f4f7; +} + +.sd-card:hover:after { + transform: scaleX(1); +} + +.card-prerequisites:hover { + transition: none; + border: none; +} + +.card-prerequisites:hover:after { + transition: none; + transform: none; +} + +.card-prerequisites:after { + display: block; + content: ''; + border-bottom: none; + background-color: #fff; + transform: none; + transition: none; + transform-origin: none; +} + + +details.sd-dropdown { + font-weight: 300; + width: auto; +} + +details.sd-dropdown:after { + border: none; + transition: none; +} + +details.sd-dropdown:hover { + border: none; + transition: none; +} + +details.sd-dropdown .sd-summary-content { + font-weight: 300; +} + +details.sd-dropdown .highlight .n { + font-weight: normal; +} + +.et-page-column1 { + float: left; + width: 70%; + font-size: 1rem; +} + +.et-page-column2 { + float: right; + padding-top: 40px; + padding-left: 60px; + padding-right: 60px; + padding-bottom: 60px; + width: 30%; +} + +.et-page-column-row:after { + content: ""; + display: table; + clear: both; +} + +/* For screens smaller than 768px (typical mobile devices) */ +@media screen and (max-width: 768px) { + .et-page-column1, .et-page-column2 { + float: none; /* Remove floats */ + width: 100%; /* Full width for both columns */ + padding: 0; + font-size: 1rem; + } + + .et-page-column2 img { + display: none; + } + .et-page-column-row:after { + content: ""; + display: table; + clear: both; + } +} + +article.pytorch-article .class .method dt { + border-top: none; +} + +article.pytorch-article .class .simple dt { + border-top: none; +} + +article.pytorch-article .function dt.sig { + border-top: none; +} + +/* Fix for Sphinx gallery thumbnails. +See https://github.com/sphinx-gallery/sphinx-gallery/issues/990 +*/ +article.pytorch-article .sphx-glr-thumbnails .sphx-glr-thumbcontainer { + width: unset; + margin-right: 0; + margin-left: 0; +} +article.pytorch-article div.section div.wy-table-responsive tbody td { + width: 50%; +} diff --git a/docs/source/_static/img/card-background.svg b/docs/source/_static/img/card-background.svg new file mode 100644 index 000000000..773515df6 --- /dev/null +++ b/docs/source/_static/img/card-background.svg @@ -0,0 +1,13 @@ + + + + + + + \ No newline at end of file diff --git a/docs/source/_static/img/generic-pytorch-logo.png b/docs/source/_static/img/generic-pytorch-logo.png new file mode 100644 index 000000000..426a14d98 Binary files /dev/null and b/docs/source/_static/img/generic-pytorch-logo.png differ diff --git a/docs/source/_static/img/pytorch-logo-dark.svg b/docs/source/_static/img/pytorch-logo-dark.svg new file mode 100755 index 000000000..5e5300038 --- /dev/null +++ b/docs/source/_static/img/pytorch-logo-dark.svg @@ -0,0 +1,33 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst new file mode 100644 index 000000000..eeb823a96 --- /dev/null +++ b/docs/source/_templates/autosummary/class.rst @@ -0,0 +1,9 @@ +.. role:: hidden + :class: hidden-section +.. currentmodule:: {{ module }} + + +{{ name | underline}} + +.. autoclass:: {{ name }} + :members: diff --git a/docs/source/_templates/autosummary/function.rst b/docs/source/_templates/autosummary/function.rst new file mode 100644 index 000000000..72abc4f50 --- /dev/null +++ b/docs/source/_templates/autosummary/function.rst @@ -0,0 +1,8 @@ +.. role:: hidden + :class: hidden-section +.. currentmodule:: {{ module }} + + +{{ name | underline}} + +.. autofunction:: {{ name }} diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 000000000..f432a1b7c --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,35 @@ +{% extends "!layout.html" %} + +{% block sidebartitle %} + + + {% include "searchbox.html" %} +{% endblock %} + + +{% block footer %} + + + + +{{ super() }} + +{% endblock %} diff --git a/docs/source/api_ref_dtypes.rst b/docs/source/api_ref_dtypes.rst new file mode 100644 index 000000000..4cb797beb --- /dev/null +++ b/docs/source/api_ref_dtypes.rst @@ -0,0 +1,18 @@ +.. _api_dtypes: + +================ +torchao.dtypes +================ + +.. currentmodule:: torchao.dtypes + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + to_nf4 + UInt4Tensor + +.. + _NF4Tensor - add after fixing torchao/dtypes/nf4tensor.py:docstring + of torchao.dtypes.nf4tensor.NF4Tensor.dequantize_scalers:6:Unexpected indentation. diff --git a/docs/source/api_ref_intro.rst b/docs/source/api_ref_intro.rst new file mode 100644 index 000000000..8f7b84ef2 --- /dev/null +++ b/docs/source/api_ref_intro.rst @@ -0,0 +1,16 @@ +``torchao`` API Reference +========================= + +This section introduces the torchao API reference. +Dive into the details of how torchao integrates with PyTorch to +optimize your machine learning models. + +.. toctree:: + :glob: + :maxdepth: 1 + :caption: Python API Reference + + api_ref_sparsity + api_ref_quantization + api_ref_dtypes + api_ref_kernel diff --git a/docs/source/api_ref_kernel.rst b/docs/source/api_ref_kernel.rst new file mode 100644 index 000000000..b43857216 --- /dev/null +++ b/docs/source/api_ref_kernel.rst @@ -0,0 +1,13 @@ +.. _api_kernel: + +================ +torchao.kernel +================ + +.. currentmodule:: torchao.kernel + +.. autosummary:: + :toctree: generated/ + :nosignatures: + +TBA diff --git a/docs/source/api_ref_quantization.rst b/docs/source/api_ref_quantization.rst new file mode 100644 index 000000000..8a580ae24 --- /dev/null +++ b/docs/source/api_ref_quantization.rst @@ -0,0 +1,23 @@ +.. _api_quantization: + +==================== +torchao.quantization +==================== + +.. currentmodule:: torchao.quantization + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + apply_weight_only_int8_quant + apply_dynamic_quant + change_linear_weights_to_int8_dqtensors + change_linear_weights_to_int8_woqtensors + change_linear_weights_to_int4_woqtensors + SmoothFakeDynQuantMixin + SmoothFakeDynamicallyQuantizedLinear + swap_linear_with_smooth_fq_linear + smooth_fq_linear_to_inference + Int4WeightOnlyGPTQQuantizer + Int4WeightOnlyQuantizer diff --git a/docs/source/api_ref_sparsity.rst b/docs/source/api_ref_sparsity.rst new file mode 100644 index 000000000..9417d9bef --- /dev/null +++ b/docs/source/api_ref_sparsity.rst @@ -0,0 +1,14 @@ +.. _api_sparsity: + +================ +torchao.sparsity +================ + +.. currentmodule:: torchao.sparsity + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + WandaSparsifier + PerChannelNormObserver diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..e1afc183d --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,189 @@ +#!/usr/bin/env python3 +# Copyright (c) Meta Platforms, Inc. and affiliates. +# All rights reserved. +# +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. +# +# +# 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. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +import os +import sys +from docutils.parsers import rst +import pytorch_sphinx_theme + +sys.path.append(os.path.abspath(".")) + +# -- General configuration ------------------------------------------------ + +# Required version of sphinx is set from docs/requirements.txt + +# 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.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.doctest", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.mathjax", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx.ext.duration", + "sphinx_tabs.tabs", + "sphinx_design", + "sphinx_gallery.gen_gallery", + "sphinx_copybutton", +] + +sphinx_gallery_conf = { + "examples_dirs": "tutorials_source", # path to your sphinx-gallery examples + "gallery_dirs": "tutorials", # path to where to save shpinx-gallery generated output + "filename_pattern": "./*.py", # any .py file in docs/source/tutorials will be built by sphinx-gallery + "backreferences_dir": "gen_modules/backreferences", # path to store the backreferences + "remove_config_comments": True, +} + +napoleon_use_ivar = True +napoleon_numpy_docstring = False +napoleon_google_docstring = True +project = "torchao" + +# Get TORCHAO_VERSION_DOCS during the build. +torchao_version_docs = os.environ.get("TORCHAO_VERSION_DOCS", None) + +# The code below will cut version displayed in the dropdown like this: +# tags like v0.1.0 = > 0.1 +# branch like release/0.1 => 0.1 +# main will remain main +# if not set will fail back to main +# the version varible is used in layout.html: https://github.com/pytorch/torchao/blob/main/docs/source/_templates/layout.html#L29 +if torchao_version_docs: + # Check if starts with release/ and set the version to the number after slash + if torchao_version_docs.startswith("release/"): + version = torchao_version_docs.split("/")[-1] + else: + # Remove "v" prefix if present + if torchao_version_docs.startswith("v"): + torchao_version_docs = torchao_version_docs[1:] + # Split to major, minor, and patch + version_components = torchao_version_docs.split(".") + + # Combine the major and minor version components: + if len(version_components) >= 2: + version = release = ".".join(version_components[:2]) + else: + # If there are not enough components, use the full version + version = release = torchao_version_docs + + html_title = " ".join((project, version, "documentation")) +# IF TORCHAO_VERSION_DOCS not set, set version to main. +else: + version = "main" + release = "main" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = [".rst"] + +# The master toctree document. +master_doc = "index" + +# General information about the project. +copyright = "2024-present, torchao Contributors" +author = "torchao Contributors" + +# 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_theme" +html_theme_path = [pytorch_sphinx_theme.get_html_theme_path()] + +# 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 = { + "collapse_navigation": False, + "display_version": True, + "logo_only": True, + "pytorch_project": "docs", + "navigation_with_keys": True, +} + +html_logo = "_static/img/pytorch-logo-dark.svg" + +html_css_files = ["css/custom.css"] + +# 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"] + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = "PyTorchdoc" + + +autosummary_generate = True + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + "torch": ("https://pytorch.org/docs/stable/", None), + "numpy": ("https://numpy.org/doc/stable/", None), +} + +# -- 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 +from sphinx.util.docfields import TypedField + +from custom_directives import CustomCardEnd, CustomCardItem, CustomCardStart +from docutils.parsers import rst + +rst.directives.register_directive("customcardstart", CustomCardStart) +rst.directives.register_directive("customcarditem", CustomCardItem) +rst.directives.register_directive("customcardend", CustomCardEnd) diff --git a/docs/source/custom_directives.py b/docs/source/custom_directives.py new file mode 100644 index 000000000..62053f278 --- /dev/null +++ b/docs/source/custom_directives.py @@ -0,0 +1,178 @@ +# Copyright (c) Meta Platforms, Inc. and affiliates. +# All rights reserved. +# +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. + +import hashlib +import os +from pathlib import Path +from typing import List +from urllib.parse import quote, urlencode + +import requests +from docutils import nodes +from docutils.parsers.rst import Directive, directives +from docutils.parsers.rst.directives.images import Image +from docutils.statemachine import StringList +from sphinx.util.docutils import SphinxDirective + +_THIS_DIR = Path(__file__).parent + +# Color palette from PyTorch Developer Day 2021 Presentation Template +YELLOW = "F9DB78" +GREEN = "70AD47" +BLUE = "00B0F0" +PINK = "FF71DA" +ORANGE = "FF8300" +TEAL = "00E5D1" +GRAY = "7F7F7F" + + +def _get_cache_path(key, ext): + filename = f"{hashlib.sha256(key).hexdigest()}{ext}" + cache_dir = _THIS_DIR / "gen_images" + cache_dir.mkdir(parents=True, exist_ok=True) + return cache_dir / filename + + +def _download(url, path): + response = requests.get(url) + response.raise_for_status() + with open(path, "wb") as file: + file.write(response.content) + + +def _fetch_image(url): + path = _get_cache_path(url.encode("utf-8"), ext=".svg") + if not path.exists(): + _download(url, path) + return os.sep + str(path.relative_to(_THIS_DIR)) + + +def _get_relpath(target, base): + target = os.sep + target + base = os.sep + base + target_path, filename = os.path.split(target) + rel_path = os.path.relpath(target_path, os.path.dirname(base)) + return os.path.normpath(os.path.join(rel_path, filename)) + + +class BaseShield(Image, SphinxDirective): + def run(self, params, alt, section) -> List[nodes.Node]: + url = f"https://img.shields.io/static/v1?{urlencode(params, quote_via=quote)}" + path = _fetch_image(url) + self.arguments = [path] + self.options["alt"] = alt + if "class" not in self.options: + self.options["class"] = [] + self.options["class"].append("shield-badge") + target = _get_relpath("supported_features.html", self.env.docname) + self.options["target"] = f"{target}#{section}" + return super().run() + + +_CARDLIST_START = """ +.. raw:: html + +
+ + +
+ +
+
+
+""" + +_CARD_TEMPLATE = """ +.. raw:: html + +
+
+ +
+
+

{header}

+
+

Topics: {tags}

+

{card_description}

+
{image}
+
+ +
+
+""" + +_CARDLIST_END = """ +.. raw:: html + +
+ +
+
+
+""" + + +class CustomCardStart(Directive): + def run(self): + para = nodes.paragraph() + self.state.nested_parse( + StringList(_CARDLIST_START.split("\n")), self.content_offset, para + ) + return [para] + + +class CustomCardItem(Directive): + option_spec = { + "header": directives.unchanged, + "image": directives.unchanged, + "link": directives.unchanged, + "card_description": directives.unchanged, + "tags": directives.unchanged, + } + + def run(self): + for key in ["header", "card_description", "link"]: + if key not in self.options: + raise ValueError(f"Key: `{key}` is missing") + + header = self.options["header"] + link = self.options["link"] + card_description = self.options["card_description"] + tags = self.options.get("tags", "") + + if "image" in self.options: + image = "" + else: + image = "_static/img/thumbnails/default.png" + + card_rst = _CARD_TEMPLATE.format( + header=header, + image=image, + link=link, + card_description=card_description, + tags=tags, + ) + card_list = StringList(card_rst.split("\n")) + card = nodes.paragraph() + self.state.nested_parse(card_list, self.content_offset, card) + return [card] + + +class CustomCardEnd(Directive): + def run(self): + para = nodes.paragraph() + self.state.nested_parse( + StringList(_CARDLIST_END.split("\n")), self.content_offset, para + ) + return [para] diff --git a/docs/source/dtypes.rst b/docs/source/dtypes.rst new file mode 100644 index 000000000..515e82872 --- /dev/null +++ b/docs/source/dtypes.rst @@ -0,0 +1,4 @@ +Dtypes +====== + +TBA diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst new file mode 100644 index 000000000..70ac60b4a --- /dev/null +++ b/docs/source/getting-started.rst @@ -0,0 +1,4 @@ +Getting Started +=============== + +TBA diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..3aee2a507 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,97 @@ +Welcome to the torchao Documentation +======================================= + +**torchao** is an open-source library that provides the functionality +to quantize and prune your models using native PyTorch. + +.. grid:: 3 + + .. grid-item-card:: :octicon:`file-code;1em` + Getting Started + :img-top: _static/img/card-background.svg + :link: getting-started.html + :link-type: url + + Learn about how to get started with torchao + and ts application in your projects. + + .. grid-item-card:: :octicon:`file-code;1em` + Concepts + :img-top: _static/img/card-background.svg + :link: dtypes.html + :link-type: url + + Learn about the key torchao concepts such + as dtypes, quantization, sparsity, among others. + + .. grid-item-card:: :octicon:`file-code;1em` + API Reference + :img-top: _static/img/card-background.svg + :link: api_ref_intro.html + :link-type: url + + A comprehensive reference for the torchao + API and its functionalities. + +Tutorials +~~~~~~~~~ + +Ready to experiment? Check out some of the +torchao tutorials. + +.. customcardstart:: + +.. customcarditem:: + :header: Template Tutorial + :card_description: A placeholder template for demo purposes + :image: _static/img/generic-pytorch-logo.png + :link: tutorials/template_tutorial.html + :tags: template + +.. customcardend:: + + +.. ---------------------------------------------------------------------- +.. Below is the toctree i.e. it defines the content of the left sidebar. +.. Each of the entry below corresponds to a file.rst in docs/source/. +.. ---------------------------------------------------------------------- + +.. toctree:: + :glob: + :maxdepth: 1 + :caption: Getting Started + :hidden: + + overview + getting-started + +.. toctree:: + :glob: + :maxdepth: 1 + :caption: Concepts + :hidden: + + dtypes + quantization + sparsity + performant_kernels + +.. toctree:: + :glob: + :maxdepth: 1 + :caption: Tutorials + :hidden: + + tutorials/template_tutorial + +.. toctree:: + :glob: + :maxdepth: 1 + :caption: API Reference + :hidden: + + api_ref_intro + api_ref_sparsity + api_ref_quantization + api_ref_dtypes + api_ref_kernel diff --git a/docs/source/overview.rst b/docs/source/overview.rst new file mode 100644 index 000000000..4c6d53206 --- /dev/null +++ b/docs/source/overview.rst @@ -0,0 +1,4 @@ +Overview +======== + +TBA diff --git a/docs/source/performant_kernels.rst b/docs/source/performant_kernels.rst new file mode 100644 index 000000000..2208d6b20 --- /dev/null +++ b/docs/source/performant_kernels.rst @@ -0,0 +1,4 @@ +Performant Kernels +================== + +TBA diff --git a/docs/source/quantization.rst b/docs/source/quantization.rst new file mode 100644 index 000000000..d96a3afc1 --- /dev/null +++ b/docs/source/quantization.rst @@ -0,0 +1,4 @@ +Quantization +============ + +TBA diff --git a/docs/source/sg_execution_times.rst b/docs/source/sg_execution_times.rst new file mode 100644 index 000000000..56399a4ee --- /dev/null +++ b/docs/source/sg_execution_times.rst @@ -0,0 +1,37 @@ + +:orphan: + +.. _sphx_glr_sg_execution_times: + + +Computation times +================= +**00:00.965** total execution time for 1 file **from all galleries**: + +.. container:: + + .. raw:: html + + + + + + + + .. list-table:: + :header-rows: 1 + :class: table table-striped sg-datatable + + * - Example + - Time + - Mem (MB) + * - :ref:`sphx_glr_tutorials_template_tutorial.py` (``tutorials_source/template_tutorial.py``) + - 00:00.965 + - 0.0 diff --git a/docs/source/sparsity.rst b/docs/source/sparsity.rst new file mode 100644 index 000000000..273ee5b77 --- /dev/null +++ b/docs/source/sparsity.rst @@ -0,0 +1,4 @@ +Sparsity +======== + +TBA diff --git a/docs/source/tutorials_source/README.txt b/docs/source/tutorials_source/README.txt new file mode 100644 index 000000000..e69de29bb diff --git a/docs/source/tutorials_source/template_tutorial.py b/docs/source/tutorials_source/template_tutorial.py new file mode 100644 index 000000000..f4de82af2 --- /dev/null +++ b/docs/source/tutorials_source/template_tutorial.py @@ -0,0 +1,58 @@ +# -*- coding: utf-8 -*- + +""" +Template Tutorial +================= + +**Author:** `FirstName LastName `_ + +**What you will learn** + +* Item 1 +* Item 2 +* Item 3 + +**Prerequisites** + +* PyTorch v2.0.0 +* GPU ??? +* Other items 3 + +""" + +######################################################################### +# Overview +# -------- +# +# Describe Why is this topic important? Add Links to relevant research papers. +# +# This tutorial walks you through the process of.... +# +# Steps +# ----- +# +# Example code (the output below is generated automatically): +# +import torch +x = torch.rand(5, 3) +print(x) + +###################################################################### +# (Optional) Additional Exercises +# ------------------------------- +# +# Add additional practice exercises for users to test their knowledge. +# Example: `NLP from Scratch `__. +# + +###################################################################### +# Conclusion +# ---------- +# +# Summarize the steps and concepts covered. Highlight key takeaways. +# +# Further Reading +# --------------- +# +# * Link1 +# * Link2