Add minimal doc setup, doc build CI job and README (#36)

Summary:
This PR adds:

- Very basic docs
- A doc build setup (taken and simplified from torchvision).
- A doc build CI job - you can verify that it works [here](https://github.com/pytorch-labs/torchcodec/actions/runs/9530809280/job/26271089159?pr=36) and if you go on the "summary" tab you can download the built docs artifacts at the bottom of the page.
- A placeholder README with some basic OSS dev instructions

F**or reviewers:** feel free to ask questions about how this works but for now, please just trust me on this. The only thing you need to review, if you want to, is the placeholder README.

There will be a lot of follow-up PRs related to the docs, namely:

- Introducing sphinx-gallery
- some styling stuff
- introducing a doc preview within the PR
- writing the actual docs...
- etc...

Pull Request resolved: #36

Reviewed By: scotts

Differential Revision: D58646833

Pulled By: NicolasHug

fbshipit-source-id: faf7035a7d5c790c42241308dee30dbf7cd692e8

.github/workflows/docs.yaml

@@ -0,0 +1,48 @@
+name: Docs
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+defaults:
+  run:
+    shell: bash -l -eo pipefail {0}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v3
+      - name: Setup conda env
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          auto-update-conda: true
+          miniconda-version: "latest"
+          activate-environment: test
+          python-version: '3.12'
+      - name: Update pip
+        run: python -m pip install --upgrade pip
+      - name: Install dependencies and FFmpeg
+        run: |
+          python -m pip install --pre torch --index-url https://download.pytorch.org/whl/nightly/cpu
+          conda install "ffmpeg=7.0.1" pkg-config -c conda-forge
+          ffmpeg -version
+      - name: Build and install torchcodec
+        run: |
+          python -m pip install -e ".[dev]" --no-build-isolation -vvv
+      - name: Install doc dependencies
+        run: |
+          cd docs
+          python -m pip install -r requirements.txt
+      - name: Build docs
+        run: |
+          cd docs
+          make html
+      - uses: actions/upload-artifact@v3
+        with:
+          name: Built-Docs
+          path: docs/build/html/

README.md

@@ -0,0 +1,56 @@
+TorchCodec
+==========
+
+Welcome to TorchCodec!
+
+TODO: Write a decent readme. For now I'm just writing basic info for OSS
+development.
+
+
+Installing from source
+----------------------
+
+Use a conda or virtual environment.
+
+Install torch nightly, e.g.:
+
+```bash
+pip install --pre torch --index-url https://download.pytorch.org/whl/nightly/cpu
+```
+
+For more options, e.g. if you need CUDA or prefer using `conda`, refer to the
+[official page](https://pytorch.org/get-started/locally/).
+
+```bash
+BUILD_AGAINST_ALL_FFMPEG_FROM_S3=1 pip install -e ".[dev]" --no-build-isolation -vvv
+```
+
+If you prefer building against an installed version of FFmpeg you can ommit the
+`BUILD_AGAINST_ALL_FFMPEG_FROM_S3=1` part. Make sure `pkg-config` is installed
+and able to find your FFmpeg installation. The easiest way to do this is to
+install both from conda:
+
+```bash
+conda install ffmpeg pkg-config -c conda-forge
+BUILD_AGAINST_ALL_FFMPEG_FROM_S3=1
+```
+
+Building the docs
+-----------------
+
+First install from source, then install the doc dependencies:
+
+```bash
+cd docs
+pip install -r requirements.txt
+```
+
+Then, still from within the `docs` directory:
+
+```bash
+make html
+```
+
+The built docs will be in `build/html`. Open in your browser to view them.
+
+Run `make clean` from time to time if you encounter issues.

docs/Makefile

@@ -0,0 +1,43 @@
+# Minimal makefile for Sphinx documentation
+#
+
+ifneq ($(EXAMPLES_PATTERN),)
+    EXAMPLES_PATTERN_OPTS := -D sphinx_gallery_conf.filename_pattern="$(EXAMPLES_PATTERN)"
+endif
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -W -j auto $(EXAMPLES_PATTERN_OPTS)
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = torchcodec
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+docset: html
+	doc2dash --name $(SPHINXPROJ) --icon $(SOURCEDIR)/_static/img/pytorch-logo-flame.png --enable-js --online-redirect-url http://pytorch.org/vision/ --force $(BUILDDIR)/html/
+
+	# Manually fix because Zeal doesn't deal well with `icon.png`-only at 2x resolution.
+	cp $(SPHINXPROJ).docset/icon.png $(SPHINXPROJ).docset/icon@2x.png
+	convert $(SPHINXPROJ).docset/icon@2x.png -resize 16x16 $(SPHINXPROJ).docset/icon.png
+
+html-noplot:  # Avoids running the gallery examples, which may take time
+	$(SPHINXBUILD) -D plot_gallery=0 -b html "${SOURCEDIR}" "$(BUILDDIR)"/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf $(SOURCEDIR)/generated_examples/  # sphinx-gallery
+	rm -rf $(SOURCEDIR)/gen_modules/  # sphinx-gallery
+	rm -rf $(SOURCEDIR)/sg_execution_times.rst  # sphinx-gallery
+	rm -rf $(SOURCEDIR)/generated/  # autosummary
+
+.PHONY: help Makefile docset
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

@@ -0,0 +1,7 @@
+sphinx-gallery>0.11
+sphinx==5.0.0
+sphinx_design
+sphinx_copybutton
+sphinx-tabs
+matplotlib
+-e git+https://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme

docs/source/_static/css/custom_torchcodec.css

@@ -0,0 +1,187 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/* sphinx-design styles for cards/tabs */
+
+
+:root {
+    --sd-color-info: #ee4c2c;
+    --sd-color-primary: #6c6c6d;
+    --sd-color-primary-highlight: #f3f4f7;
+    --sd-color-card-border-hover: #ee4c2c;
+    --sd-color-card-border: #f3f4f7;
+    --sd-color-card-background: #fff;
+    --sd-color-card-text: inherit;
+    --sd-color-card-header: transparent;
+    --sd-color-card-footer: transparent;
+    --sd-color-tabs-label-active: #ee4c2c;
+    --sd-color-tabs-label-hover: #ee4c2c;
+    --sd-color-tabs-label-inactive: #6c6c6d;
+    --sd-color-tabs-underline-active: #ee4c2c;
+    --sd-color-tabs-underline-hover: #fabdbd;
+    --sd-color-tabs-underline-inactive: transparent;
+    --sd-color-tabs-overline: rgb(222, 222, 222);
+    --sd-color-tabs-underline: rgb(222, 222, 222);
+}
+
+.sd-text-info {
+    color: #ee4c2c;
+}
+
+.sd-card-img-top {
+    background: #ee4c2c;
+    height: 5px !important;
+}
+
+.sd-card {
+    position: relative;
+    background-color: #fff;
+    opacity: 1.0;
+    border-radius: 0px;
+    width: 30%;
+    border: none;
+    padding-bottom: 0px;
+}
+
+
+.sd-card-img:hover {
+    opacity: 1.0;
+    background-color: #f3f4f7;
+}
+
+
+.sd-card:after {
+    display: block;
+    opacity: 1;
+    content: '';
+    border-bottom: solid 1px #ee4c2c;
+    background-color: #fff;
+    transform: scaleX(0);
+    transition: transform .250s ease-in-out;
+    transform-origin:  0% 50%;
+}
+
+.sd-card:hover {
+    background-color: #fff;
+    opacity: 1;
+    border-top: 1px solid #f3f4f7;
+    border-left: 1px solid #f3f4f7;
+    border-right: 1px solid #f3f4f7;
+}
+
+.sd-card:hover:after {
+    transform: scaleX(1);
+}
+
+.card-prerequisites:hover {
+    transition: none;
+    border: none;
+}
+
+.card-prerequisites:hover:after {
+    transition: none;
+    transform: none;
+}
+
+.card-prerequisites:after {
+    display: block;
+    content: '';
+    border-bottom: none;
+    background-color: #fff;
+    transform: none;
+    transition: none;
+    transform-origin: none;
+}
+
+
+details.sd-dropdown {
+    font-weight: 300;
+    width: auto;
+}
+
+details.sd-dropdown:after {
+    border: none;
+    transition: none;
+}
+
+details.sd-dropdown:hover {
+    border: none;
+    transition: none;
+}
+
+details.sd-dropdown .sd-summary-content {
+    font-weight: 300;
+}
+
+details.sd-dropdown .highlight .n {
+    font-weight: normal;
+}
+
+.et-page-column1 {
+  float: left;
+  width: 70%;
+  font-size: 1rem;
+}
+
+.et-page-column2 {
+  float: right;
+  padding-top: 40px;
+  padding-left: 60px;
+  padding-right: 60px;
+  padding-bottom: 60px;
+  width: 30%;
+}
+
+.et-page-column-row:after {
+  content: "";
+  display: table;
+  clear: both;
+}
+
+/* For screens smaller than 768px (typical mobile devices) */
+@media screen and (max-width: 768px) {
+  .et-page-column1, .et-page-column2 {
+    float: none; /* Remove floats */
+    width: 100%; /* Full width for both columns */
+    padding: 0;
+    font-size: 1rem;
+  }
+
+  .et-page-column2 img {
+    display: none;
+  }
+  .et-page-column-row:after {
+    content: "";
+    display: table;
+    clear: both;
+  }
+}
+
+article.pytorch-article .class .method dt {
+    border-top: none;
+}
+
+article.pytorch-article .class .simple dt {
+    border-top: none;
+}
+
+article.pytorch-article .function dt.sig {
+    border-top: none;
+}
+
+/* Fix for Sphinx gallery thumbnails.
+See https://github.com/sphinx-gallery/sphinx-gallery/issues/990
+*/
+article.pytorch-article .sphx-glr-thumbnails .sphx-glr-thumbcontainer {
+    width: unset;
+    margin-right: 0;
+    margin-left: 0;
+}
+article.pytorch-article div.section div.wy-table-responsive tbody td {
+    width: 50%;
+}