Add basic sphinx-gallery example (#44)

Summary:
This PR adds a basic example of an... example.

The examples are created with the sphinx-gallery extension and allow us to write notebook-style code. The current one is very basic and looks like this:

![screen](https://github.com/pytorch-labs/torchcodec/assets/1190450/322fef23-059f-4733-91e1-3cc60722ed19)

Pull Request resolved: #44

Reviewed By: scotts

Differential Revision: D58810557

Pulled By: NicolasHug

fbshipit-source-id: 72d689d3b264a8a2cae4a1bc87753754f1b272bf

.gitignore

@@ -12,10 +12,11 @@ frame180.* # output from smoke test
 
 docs/build
 # sphinx-gallery
-docs/source/auto_examples/
+docs/source/generated_examples/
 docs/source/gen_modules/
 docs/source/generated/
 docs/source/models/generated/
+docs/source/sg_execution_times.rst
 # pytorch-sphinx-theme gets installed here
 docs/src
 

README.md

@@ -53,4 +53,9 @@ make html
 
 The built docs will be in `build/html`. Open in your browser to view them.
 
+To avoid building the examples (which execute python code and can take time) you
+can use `make html-noplot`. To build a subset of specific examples instead of
+all of them, you can use a regex like `EXAMPLES_PATTERN="plot_the_best_example*"
+make html`.
+
 Run `make clean` from time to time if you encounter issues.

docs/source/conf.py

@@ -50,11 +50,40 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx.ext.duration",
+    "sphinx_gallery.gen_gallery",
     "sphinx_tabs.tabs",
     "sphinx_design",
     "sphinx_copybutton",
 ]
 
+sphinx_gallery_conf = {
+    "examples_dirs": "../../examples/",  # path to your example scripts
+    "gallery_dirs": "generated_examples",  # path to where to save gallery generated output
+    "filename_pattern": "basic*",
+    "backreferences_dir": "gen_modules/backreferences",
+    "doc_module": ("torchcodec",),
+    "remove_config_comments": True,
+}
+
+# We override sphinx-gallery's example header to prevent sphinx-gallery from
+# creating a note at the top of the renderred notebook.
+# https://github.com/sphinx-gallery/sphinx-gallery/blob/451ccba1007cc523f39cbcc960ebc21ca39f7b75/sphinx_gallery/gen_rst.py#L1267-L1271
+# This is because we also want to add a link to google collab, so we write our own note in each example.
+from sphinx_gallery import gen_rst
+
+gen_rst.EXAMPLE_HEADER = """
+.. DO NOT EDIT.
+.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
+.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
+.. "{0}"
+.. LINE NUMBERS ARE GIVEN BELOW.
+
+.. rst-class:: sphx-glr-example-title
+
+.. _sphx_glr_{1}:
+
+"""
+
 napoleon_use_ivar = True
 napoleon_numpy_docstring = False
 napoleon_google_docstring = True
@@ -142,3 +171,33 @@
     "PIL": ("https://pillow.readthedocs.io/en/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
 }
+
+
+def inject_minigalleries(app, what, name, obj, options, lines):
+    """Inject a minigallery into a docstring.
+
+    This avoids having to manually write the .. minigallery directive for every item we want a minigallery for,
+    as it would be easy to miss some.
+
+    This callback is called after the .. auto directives (like ..autoclass) have been processed,
+    and modifies the lines parameter inplace to add the .. minigallery that will show which examples
+    are using which object.
+
+    It's a bit hacky, but not *that* hacky when you consider that the recommended way is to do pretty much the same,
+    but instead with templates using autosummary (which we don't want to use):
+    (https://sphinx-gallery.github.io/stable/configuration.html#auto-documenting-your-api-with-links-to-examples)
+
+    For docs on autodoc-process-docstring, see the autodoc docs:
+    https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+    """
+
+    if what in ("class", "function"):
+        lines.append(f".. minigallery:: {name}")
+        lines.append(f"    :add-heading: Examples using ``{name.split('.')[-1]}``:")
+        # avoid heading entirely to avoid warning. As a bonud it actually renders better
+        lines.append("    :heading-level: 9")
+        lines.append("\n")
+
+
+def setup(app):
+    app.connect("autodoc-process-docstring", inject_minigalleries)

docs/source/index.rst

@@ -2,3 +2,24 @@ Welcome to the TorchCodec documentation
 =======================================
 
 Still WIP :)
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Examples
+
+   generated_examples/index
+
+
+
+API REF
+-------
+
+.. TODO: Move that separately later. This is just for illustration purpose for
+.. now.
+
+.. autosummary::
+    :toctree: generated/
+    :template: class.rst
+
+    torchcodec.decoders.SimpleVideoDecoder

examples/README.rst

@@ -0,0 +1,4 @@
+.. _gallery:
+
+Examples and tutorials
+======================

examples/basic_example_remove_me.py

@@ -0,0 +1,34 @@
+"""
+=============
+Basic Example
+=============
+
+Remove this!
+"""
+
+# %%
+print("This is a cell that gets executerd")
+# %%
+print("And another cell.")
+
+# %%
+# We can write rst cells too!
+# ---------------------------
+#
+# As if we're writing normal docs/docstrings. Let's reference the
+# :class:`~torchcodec.decoders.SimpleVideoDecoder` class. Click on this and it
+# should bring you to its docstring!! In the docstring, you should see a
+# backreference to this example as well!
+#
+# And of course we can write normal code
+
+# %%
+from torchcodec.decoders import SimpleVideoDecoder
+
+try:
+    SimpleVideoDecoder("bad_path")
+except ValueError as e:
+    print(f"Ooops:\n {e}")
+
+# %%
+print("All good!")

src/torchcodec/decoders/_simple_video_decoder.py

@@ -6,6 +6,7 @@
 
 
 class SimpleVideoDecoder:
+    """TODO: Add docstring."""
 
     def __init__(self, source: Union[str, bytes, torch.Tensor]):
         # TODO: support Path objects.