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,28 +33,42 @@ 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:
 
-1. Clone the executorch repo to your machine.
+1. Clone the ExecuTorch repo to your machine.
 
 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
+   the `conda create` command.
+   ```
+
+   ```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:
 
    ```
@@ -132,15 +148,15 @@ Python and C++ documentation in the form of HTML pages.
 
 ### Python APIs
 
-We generate Python API documentation through Sphinx, bootstrapping [Pytorch's
+We generate Python API documentation through Sphinx, bootstrapping [PyTorch's
 Sphinx theme](https://github.com/pytorch/pytorch_sphinx_theme) for
-a cohesive look with the existing Pytorch API documentation.
+a cohesive look with the existing PyTorch API documentation.
 
 The setup for Python documentation lies within `source_py/`. To set up Sphinx, a
 `conf.py` configuration file is required. We can specify ways to generate
 documentation here. Specifically, the most important/relevant parts are:
 
-* Make sure to add a path to the directory above the directory you're trying to generate documentation for. For example, since we want to generate documenation for the `executorch/` directory. This tells Sphinx where to find the code to generate docs for.
+* Make sure to add a path to the directory above the directory you're trying to generate documentation for. For example, since we want to generate documentation for the `executorch/` directory. This tells Sphinx where to find the code to generate docs for.
 
 * `extensions` contains extension modules. For auto-generating APIs, make sure to include `sphinx.ext.autodoc`.
 * `autodoc_mock_imports` is where you put imports that Sphinx is unable to access. Sphinx runs your code in order to autogenerate the docs, so for any libraries that it unable to access due to it being outside of the directory, or containing c++ bindings, we need to specify it in the `autodoc_mock_imports` list. You can see what modules Sphinx is confused by when you run into importing errors when generating docs.
@@ -170,7 +186,7 @@ landing page under `index.rst`. A sample of this structure can be found in
 A diagram of how the files work together:
 ![image](python_docs.png)
 
-To view your changes on the executorch website, you can follow the same steps
+To view your changes on the ExecuTorch website, you can follow the same steps
 listed in the "General Documentation" section.
 
 To view just the auto-generated pages:

docs/source/_templates/layout.html

@@ -43,6 +43,6 @@
 {% block footer %}
 {{ super() }}
 <script script type="text/javascript">
-    var collapsedSections = ['Introduction', 'Getting Started', 'Exporting to ExecuTorch', 'IR Specification', 'Compiler Entry Points', 'Runtime', 'Quantization', 'Kernel Library', 'SDK', 'Tutorials']
+    var collapsedSections = ['Introduction', 'Getting Started', 'Exporting to ExecuTorch', 'API Reference', 'IR Specification', 'Compiler Entry Points', 'Runtime', 'Quantization', 'Kernel Library', 'SDK', 'Tutorials']
 </script>
 {% endblock %}

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", "tutorial-template.md"]
+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

@@ -185,13 +185,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.