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 %} -
- {{ version }} ▼ -
- {% 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 +=========