Port docs to new theme

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

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

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

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

docs/source/index.rst

@@ -91,18 +91,16 @@ Encoding
 
 .. toctree::
    :maxdepth: 1
-   :caption: TorchCodec documentation
+   :caption: Installation
    :hidden:
 
-   Home <self>
-   glossary
+   Installation <https://github.com/pytorch/torchcodec?tab=readme-ov-file#installing-torchcodec>
 
 .. toctree::
    :maxdepth: 1
-   :caption: Examples and tutorials
+   :caption: Tutorials
    :hidden:
 
-   Installation instructions <https://github.com/pytorch/torchcodec?tab=readme-ov-file#installing-torchcodec>
    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

examples/README.rst

@@ -1,4 +1,4 @@
 .. _gallery:
 
-Interactive examples
-====================
+Tutorials
+=========