From 13cec957f178edbc04341330b4eb38dce225e4be Mon Sep 17 00:00:00 2001 From: Nicolas Hug Date: Thu, 3 Jul 2025 14:55:48 +0100 Subject: [PATCH 1/4] Port docs to new theme --- docs/requirements.txt | 13 ++++-- docs/source/api_ref.rst | 70 +++++++++++++++++++++++++++++ docs/source/api_ref_decoders.rst | 29 ------------ docs/source/api_ref_samplers.rst | 19 -------- docs/source/api_ref_torchcodec.rst | 17 ------- docs/source/conf.py | 72 +++++++++++++++++++++++++----- docs/source/index.rst | 19 ++++---- examples/README.rst | 4 +- 8 files changed, 153 insertions(+), 90 deletions(-) create mode 100644 docs/source/api_ref.rst delete mode 100644 docs/source/api_ref_decoders.rst delete mode 100644 docs/source/api_ref_samplers.rst delete mode 100644 docs/source/api_ref_torchcodec.rst 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/api_ref.rst b/docs/source/api_ref.rst new file mode 100644 index 000000000..d845e2a20 --- /dev/null +++ b/docs/source/api_ref.rst @@ -0,0 +1,70 @@ + +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_basic_example.py`. +For an audio decoder tutorial, see: :ref:`sphx_glr_generated_examples_audio_decoding.py`. + + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: class.rst + + VideoDecoder + AudioDecoder + + +.. autosummary:: + :toctree: generated/ + :nosignatures: + :template: dataclass.rst + + VideoStreamMetadata + AudioStreamMetadata + +.. _samplers: + +torchcodec.samplers +------------------- + + +.. currentmodule:: torchcodec.samplers + +For a tutorial, see: :ref:`sphx_glr_generated_examples_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 bb55cfae3..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_basic_example.py`. -For an audio decoder tutorial, see: :ref:`sphx_glr_generated_examples_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_samplers.rst b/docs/source/api_ref_samplers.rst deleted file mode 100644 index c72c4d825..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_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 b9d3eb584..01c0d6182 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", ] @@ -121,15 +125,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" @@ -162,22 +164,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/" +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": "", + "feedback_url": "https://github.com/pytorch/", + "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 d6d319901..760ca5526 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -69,18 +69,16 @@ We achieve these capabilities through: .. 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 @@ -90,6 +88,11 @@ We achieve these capabilities through: :caption: API Reference :hidden: - api_ref_torchcodec - api_ref_decoders - 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 +========= From 2fca77da2168269cd28c2c7768452064a99af1df Mon Sep 17 00:00:00 2001 From: Nicolas Hug Date: Thu, 3 Jul 2025 15:43:48 +0100 Subject: [PATCH 2/4] dont error on warnings --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From c09144060cd765b065c0aa95d521c0e059281715 Mon Sep 17 00:00:00 2001 From: Nicolas Hug Date: Mon, 7 Jul 2025 10:40:32 +0100 Subject: [PATCH 3/4] Fix some stuff --- docs/source/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index e5b076b31..9e759945d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -176,7 +176,7 @@ def __call__(self, filename): html_theme = "pytorch_sphinx_theme2" html_theme_path = [pytorch_sphinx_theme2.get_html_theme_path()] -ogp_site_url = "http://pytorch.org/" +ogp_site_url = "http://pytorch.org/torchcodec" ogp_image = "https://pytorch.org/assets/images/social-share.jpg" @@ -227,8 +227,8 @@ def __call__(self, filename): "display_github": True, "github_url": "https://github.com", "github_user": "pytorch", - "github_repo": "", - "feedback_url": "https://github.com/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", []), From f7c9025751a52056d5ae19640eb83a7ef6f32b67 Mon Sep 17 00:00:00 2001 From: Nicolas Hug Date: Mon, 7 Jul 2025 16:51:31 +0100 Subject: [PATCH 4/4] Remove layout.hmtl --- docs/source/_templates/layout.html | 21 --------------------- 1 file changed, 21 deletions(-) delete mode 100644 docs/source/_templates/layout.html 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 %} -
- {{ version }} ▼ -
- {% include "searchbox.html" %} -{% endblock %} - - -{% block footer %} - - - - -{% endblock %}