Fix formatting and cleanup (#593)

Summary:

- Added a check to the custom role to ensure sphx-gallery outputs are not affected.
- Removed template tutorial custom card from index.rst
- Don't generate tutorials/index.html - because sphinx autogenerates a page with all tutorials that is hard to format.
- Added sys.path so we can use autodoc in .md files.

Reviewed By: mergennachin

Differential Revision: D49878715

Author: Svetlana Karslioglu

docs/README.md

@@ -4,6 +4,8 @@ Welcome to the ExecuTorch documentation! This README.md will provide an
 overview of the ExecuTorch docs and its features, as well as instructions on
 how to contribute and build locally.
 
+All current documentation is located in the `docs/source` directory.
+
 <!-- toc -->
 
 - [Toolchain Overview](#toolchain-overview)
@@ -31,7 +33,7 @@ We support both `.rst` and `.md` files but prefer the content to be authored in
 
 ## Building Locally
 
-Documentation dependancies are stored in
+Documentation dependencies are stored in
 [.ci/docker/requirements-ci.txt](https://github.com/pytorch/executorch/blob/main/.ci/docker/requirements-ci.txt).
 
 To build the documentation locally:
@@ -40,19 +42,33 @@ To build the documentation locally:
 
 1. Switch to the `docs/` directory.
 
-1. Start a virtual environment:
+1. If you don't have it already, start a conda environment:
+
+   ```{note}
+   The below command generates a completely new environment and resets
+   any existing dependencies. If you have an environment already, skip
+   this step.
+   ```
+
+   ```bash
+   conda create -yn executorch python=3.10.0
+   conda activate executorch
+   ```
+
+1. Install dependencies:
 
    ```bash
-   virtualenv venv
-   source venv/bin/activate
+   pip3 install -r ./.ci/docker/requirements-ci.txt
    ```
 
-1. Install dependancies:
+1. Run:
 
    ```bash
-   pip3 install -r ../.ci/docker/requirements-ci.txt
+   bash install_requirements.sh
    ```
 
+1. Go to the `docs/` directory.
+
 1. Build the documentation set:
 
    ```

docs/source/conf.py

@@ -72,6 +72,7 @@
 
 sphinx_gallery_conf = {
     "examples_dirs": ["tutorials_source"],
+    "ignore_pattern": "template_tutorial.py",
     "gallery_dirs": ["tutorials"],
     "filename_pattern": "/tutorials_source/",
     "promote_jupyter_magic": True,
@@ -91,6 +92,8 @@
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns += sphinx_gallery_conf["examples_dirs"]
+exclude_patterns += ["*/index.rst"]
 
 # autosectionlabel throws warnings if section names are duplicated.
 # The following tells autosectionlabel to not throw a warning for

docs/source/executorch_custom_versions.py

@@ -56,7 +56,20 @@ def replace_variables(app, doctree, docname):
         new_text = node.astext()
         for var, value in variables.items():
             new_text = new_text.replace(var, value)
-        node.parent.replace(node, nodes.literal_block(new_text, new_text))
+
+        classes = node.get("classes", [])
+        # check if the output is generated by sphinx-gallery and if yes, keep the original
+        # CSS classes. Otherwise, the sphinx-gallery generated outputs are
+        # formatted as regular code blocks with gray background instead of pink.
+        is_sphinx_gallery = any("sphx-glr" in class_ for class_ in classes)
+        if is_sphinx_gallery:
+            new_literal_block = nodes.literal_block(new_text, new_text, classes=classes)
+        else:
+            new_literal_block = nodes.literal_block(
+                new_text, new_text, classes=["highlight-none", "notranslate"]
+            )
+
+        node.parent.replace(node, new_literal_block)
 
 
 def setup(app):

docs/source/index.rst

@@ -173,13 +173,6 @@ ExecuTorch tutorials.
 
 .. customcardstart::
 
-.. customcarditem::
-   :header: Template Tutorial
-   :card_description: A template tutorial. To be deleted.
-   :image: _static/img/generic-pytorch-logo.png
-   :link: tutorials/template_tutorial.html
-   :tags: Template
-
 .. customcarditem::
    :header: Exporting to ExecuTorch Tutorial
    :card_description: A tutorial for exporting a model and lowering a it to be runnable on the ExecuTorch runtime.