diff --git a/docs/Makefile b/docs/Makefile
index 2757c000a..b60a687dc 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -6,7 +6,7 @@ ifneq ($(EXAMPLES_PATTERN),)
endif
# You can set these variables from the command line.
-SPHINXOPTS = -W -j auto $(EXAMPLES_PATTERN_OPTS)
+SPHINXOPTS = -j auto $(EXAMPLES_PATTERN_OPTS)
SPHINXBUILD = sphinx-build
SPHINXPROJ = torchcodec
SOURCEDIR = source
diff --git a/docs/requirements.txt b/docs/requirements.txt
index d5fa5091b..55e5282d2 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,11 +1,16 @@
-sphinx-gallery>0.11
-sphinx==5.0.0
-sphinx_design
+sphinx-gallery==0.11.1
+sphinx==5.3.0
+sphinx-design==0.4.0
sphinx_copybutton
sphinx-tabs
+sphinxcontrib.katex==0.8.6
+sphinxext-opengraph==0.9.1
+docutils==0.16
+sphinxcontrib-mermaid==1.0.0
+sphinx-sitemap==2.7.1
matplotlib
torchvision
ipython
fsspec
aiohttp
--e git+https://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
+-e git+https://github.com/pytorch/pytorch_sphinx_theme.git@pytorch_sphinx_theme2#egg=pytorch_sphinx_theme2
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
deleted file mode 100644
index 010a4d6d7..000000000
--- a/docs/source/_templates/layout.html
+++ /dev/null
@@ -1,21 +0,0 @@
-{% extends "!layout.html" %}
-
-{% block sidebartitle %}
-
- {% include "searchbox.html" %}
-{% endblock %}
-
-
-{% block footer %}
-
-
-
-
-{% endblock %}
diff --git a/docs/source/api_ref.rst b/docs/source/api_ref.rst
new file mode 100644
index 000000000..4a5461e05
--- /dev/null
+++ b/docs/source/api_ref.rst
@@ -0,0 +1,89 @@
+
+API Ref
+=======
+
+.. _torchcodec:
+
+torchcodec
+----------
+
+.. currentmodule:: torchcodec
+
+
+.. autosummary::
+ :toctree: generated/
+ :nosignatures:
+ :template: dataclass.rst
+
+ Frame
+ FrameBatch
+ AudioSamples
+
+
+.. _decoders:
+
+torchcodec.decoders
+-------------------
+
+.. currentmodule:: torchcodec.decoders
+
+
+For a video decoder tutorial, see: :ref:`sphx_glr_generated_examples_decoding_basic_example.py`.
+For an audio decoder tutorial, see: :ref:`sphx_glr_generated_examples_decoding_audio_decoding.py`.
+
+
+.. autosummary::
+ :toctree: generated/
+ :nosignatures:
+ :template: class.rst
+
+ VideoDecoder
+ AudioDecoder
+
+
+.. autosummary::
+ :toctree: generated/
+ :nosignatures:
+ :template: dataclass.rst
+
+ VideoStreamMetadata
+ AudioStreamMetadata
+
+.. _encoders:
+
+torchcodec.encoders
+-------------------
+
+.. currentmodule:: torchcodec.encoders
+
+
+For an audio decoder tutorial, see: :ref:`sphx_glr_generated_examples_encoding_audio_encoding.py`.
+
+
+.. autosummary::
+ :toctree: generated/
+ :nosignatures:
+ :template: class.rst
+
+ AudioEncoder
+
+
+.. _samplers:
+
+torchcodec.samplers
+-------------------
+
+
+.. currentmodule:: torchcodec.samplers
+
+For a tutorial, see: :ref:`sphx_glr_generated_examples_decoding_sampling.py`.
+
+.. autosummary::
+ :toctree: generated/
+ :nosignatures:
+ :template: function.rst
+
+ clips_at_regular_indices
+ clips_at_random_indices
+ clips_at_regular_timestamps
+ clips_at_random_timestamps
diff --git a/docs/source/api_ref_decoders.rst b/docs/source/api_ref_decoders.rst
deleted file mode 100644
index 0ae159c37..000000000
--- a/docs/source/api_ref_decoders.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-.. _decoders:
-
-===================
-torchcodec.decoders
-===================
-
-.. currentmodule:: torchcodec.decoders
-
-
-For a video decoder tutorial, see: :ref:`sphx_glr_generated_examples_decoding_basic_example.py`.
-For an audio decoder tutorial, see: :ref:`sphx_glr_generated_examples_decoding_audio_decoding.py`.
-
-
-.. autosummary::
- :toctree: generated/
- :nosignatures:
- :template: class.rst
-
- VideoDecoder
- AudioDecoder
-
-
-.. autosummary::
- :toctree: generated/
- :nosignatures:
- :template: dataclass.rst
-
- VideoStreamMetadata
- AudioStreamMetadata
diff --git a/docs/source/api_ref_encoders.rst b/docs/source/api_ref_encoders.rst
deleted file mode 100644
index 52c7295bc..000000000
--- a/docs/source/api_ref_encoders.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-.. _encoders:
-
-===================
-torchcodec.encoders
-===================
-
-.. currentmodule:: torchcodec.encoders
-
-
-For an audio decoder tutorial, see: :ref:`sphx_glr_generated_examples_encoding_audio_encoding.py`.
-
-
-.. autosummary::
- :toctree: generated/
- :nosignatures:
- :template: class.rst
-
- AudioEncoder
diff --git a/docs/source/api_ref_samplers.rst b/docs/source/api_ref_samplers.rst
deleted file mode 100644
index 0cec98e62..000000000
--- a/docs/source/api_ref_samplers.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-.. _samplers:
-
-===================
-torchcodec.samplers
-===================
-
-.. currentmodule:: torchcodec.samplers
-
-For a tutorial, see: :ref:`sphx_glr_generated_examples_decoding_sampling.py`.
-
-.. autosummary::
- :toctree: generated/
- :nosignatures:
- :template: function.rst
-
- clips_at_regular_indices
- clips_at_random_indices
- clips_at_regular_timestamps
- clips_at_random_timestamps
diff --git a/docs/source/api_ref_torchcodec.rst b/docs/source/api_ref_torchcodec.rst
deleted file mode 100644
index f6d3fef36..000000000
--- a/docs/source/api_ref_torchcodec.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-.. _torchcodec:
-
-===================
-torchcodec
-===================
-
-.. currentmodule:: torchcodec
-
-
-.. autosummary::
- :toctree: generated/
- :nosignatures:
- :template: dataclass.rst
-
- Frame
- FrameBatch
- AudioSamples
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 496a24068..9e759945d 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -29,7 +29,7 @@
import os
import sys
-import pytorch_sphinx_theme
+import pytorch_sphinx_theme2
import torchcodec
sys.path.append(os.path.abspath("."))
@@ -55,6 +55,10 @@
"sphinx_tabs.tabs",
"sphinx_design",
"sphinx_copybutton",
+ "sphinx_sitemap",
+ "sphinxcontrib.mermaid",
+ "pytorch_sphinx_theme2",
+ "sphinxext.opengraph",
]
@@ -130,15 +134,13 @@ def __call__(self, filename):
napoleon_google_docstring = True
-# 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"]
html_title = f"TorchCodec {torchcodec.__version__} Documentation"
+html_baseurl = "https://github.com/pytorch/torchcodec"
# The master toctree document.
master_doc = "index"
@@ -171,22 +173,70 @@ def __call__(self, filename):
# 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()]
+html_theme = "pytorch_sphinx_theme2"
+html_theme_path = [pytorch_sphinx_theme2.get_html_theme_path()]
+
+ogp_site_url = "http://pytorch.org/torchcodec"
+ogp_image = "https://pytorch.org/assets/images/social-share.jpg"
+
# 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,
+ "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/torchcodec",
+ "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/torchcodec",
+ "icon": "fa-brands fa-python",
+ },
+ ],
+ "use_edit_page_button": True,
+ "navbar_center": "navbar-nav",
+}
+theme_variables = pytorch_sphinx_theme2.get_theme_variables()
+
+templates_path = [
+ "_templates",
+ os.path.join(os.path.dirname(pytorch_sphinx_theme2.__file__), "templates"),
+]
+
+html_context = {
+ "theme_variables": theme_variables,
+ "display_github": True,
+ "github_url": "https://github.com",
+ "github_user": "pytorch",
+ "github_repo": "torchcodec",
+ "feedback_url": "https://github.com/pytorch/torchcodec",
+ "github_version": "main",
+ "doc_path": "docs/source",
+ "library_links": theme_variables.get("library_links", []),
+ "community_links": theme_variables.get("community_links", []),
+ "language_bindings_links": html_theme_options.get("language_bindings_links", []),
}
+
html_logo = "_static/img/pytorch-logo-dark.svg"
html_css_files = ["css/custom_torchcodec.css"]
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 55f3edf28..b2ec82944 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -91,18 +91,16 @@ Encoding
.. toctree::
:maxdepth: 1
- :caption: TorchCodec documentation
+ :caption: Installation
:hidden:
- Home
- glossary
+ Installation
.. toctree::
:maxdepth: 1
- :caption: Examples and tutorials
+ :caption: Tutorials
:hidden:
- Installation instructions
generated_examples/index
@@ -112,7 +110,11 @@ Encoding
:caption: API Reference
:hidden:
- api_ref_torchcodec
- api_ref_decoders
- api_ref_encoders
- api_ref_samplers
+ api_ref
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Glossary
+ :hidden:
+
+ glossary
diff --git a/examples/README.rst b/examples/README.rst
index 422be9ee7..a85ed3e33 100644
--- a/examples/README.rst
+++ b/examples/README.rst
@@ -1,4 +1,4 @@
.. _gallery:
-Interactive examples
-====================
+Tutorials
+=========