[WAIT TO MERGE] Flyte docs overhaul

.gitignore

@@ -30,12 +30,10 @@ vendor/
 /docker/sandbox-bundled/images/tar
 **/bin/
 docs/_tags/
-docs/flytectl
-docs/protos
-docs/flytekit
+docs/api/flytectl
+docs/api/flyteidl
+docs/api/flytekit/*/generated
 docs/flytesnacks
 docs/examples
 docs/_src
 docs/_projects
-docs/api
-docs/tests

docs/Makefile

@@ -20,4 +20,4 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 clean:
-	rm -rf _build _src _tags api flytectl flytekit flytesnacks protos examples tests _projects
+	rm -rf _build _src _tags flytesnacks examples api/flytekit api/flytectl api/flyteidl

docs/README.md

@@ -2,14 +2,15 @@
 
 ## Prerequisites
 
-* `conda` (We recommend Miniconda installed with an [official installer](https://docs.conda.io/projects/miniconda/en/latest/index.html#latest-miniconda-installer-links))
+Install the following prerequisites:
 
+* `conda` (We recommend Miniconda installed with an [official installer](https://docs.conda.io/projects/miniconda/en/latest/index.html#latest-miniconda-installer-links))
 * [`conda-lock`](https://github.com/conda/conda-lock)
 
 
 ## Set up the build environment
 
-In the `flyteorg/flyte` root directory do:
+In the `flyteorg/flyte` root directory, run the following commands:
 
 ```bash
 $ conda-lock install --name monodocs-env monodocs-environment.lock.yaml
@@ -20,12 +21,16 @@ $ pip install ./flyteidl
 This creates a new environment called `monodocs-env` with all the dependencies needed to build the docs. You can choose a different environment name if you like.
 
 
-## Building the docs
+## Build the docs
 
-In the `flyteorg/flyte` root directory make sure you have activated the `monodocs-env` (or whatever you called it) environment and do:
+In the `flyteorg/flyte` root directory, run the following command:
 
 ```bash
 $ make docs
 ```
 
-The resulting `html` files will be in `docs/_build/html`.
+The resulting `html` files will be in `docs/_build/html`. You can view them by running the following command:
+
+```bash
+$ open docs/_build/html/index.html
+```

docs/_ext/import_projects.py

@@ -55,32 +55,6 @@ class Project:
 
 VERSION_PATTERN = r"^v[0-9]+.[0-9]+.[0-9]+$"
 
-
-class ListTableToc(SphinxDirective):
-    """Custom directive to convert list-table into both list-table and toctree."""
-
-    has_content = True
-
-    def run(self) -> list:
-        return [self.parse()]
-
-    def parse(self):
-        """Parses the list-table and adds a toctree"""
-        toc = ""
-
-        # finds all doc references in the form <doc/path>
-        for doc in re.findall(r"<(.+)>", self.block_text):
-            toc += f"\n{doc}"
-
-        container = nodes.container("")
-        toc = inspect.cleandoc(TOC_TEMPLATE.format(toc=toc))
-        table = inspect.cleandoc(TABLE_TEMPLATE.format(content=self.block_text))
-        content = f"{toc}\n\n{table}"
-
-        self.state.nested_parse(StringList(string2lines(content)), 0, container)
-        return container
-
-
 def update_sys_path_for_flytekit(import_project_config: ImportProjectsConfig):
     flytekit_dir = Path(import_project_config.flytekit_api_dir).resolve(strict=True)
     flytekit_src_dir = flytekit_dir / "flytekit"
@@ -100,6 +74,7 @@ def update_sys_path_for_flytekit(import_project_config: ImportProjectsConfig):
         if possible_plugin_dir.is_dir() and plugin_path.exists():
             sys.path.insert(0, str(possible_plugin_dir))
 
+
 def update_html_context(project: Project, tag: str, commit: str, config: Config):
     tag_url = "#" if tag == "dev" else f"{project.source}/releases/tag/{tag}"
     commit_url = f"{project.source}/tree/{commit}"
@@ -179,9 +154,6 @@ def import_projects(app: Sphinx, config: Config):
     # remove cloned directories
     shutil.rmtree(import_projects_config.clone_dir)
 
-    # add flytekit and plugins to path so that API reference can build
-    update_sys_path_for_flytekit(import_projects_config)
-
     # add functions to clean up source and docstring refs
     for i, (patt, repl) in enumerate(
         import_projects_config.source_regex_mapping.items()
@@ -230,24 +202,10 @@ def replace_refs_in_docstrings(
         lines[i] = text
 
 
-def add_list_table_toc(app: Sphinx, docname: str, source: List[str]):
-    """This replaces list-table directives in specific documents with list-table-toc.
-
-    This is important for automatically generating a toctree and list-table from
-    a list-table.
-    """
-    if docname in app.config.import_projects_config["list_table_toc"]:
-        text = source[0]
-        text = re.sub(r"{list-table}", r"{list-table-toc}", text)
-        source[0] = text
-
-
 def setup(app: Sphinx) -> dict:
     app.add_config_value("import_projects_config", None, False)
     app.add_config_value("import_projects", None, False)
-    app.add_directive("list-table-toc", ListTableToc)
     app.connect("config-inited", import_projects, priority=0)
-    app.connect("source-read", add_list_table_toc, priority=0)
 
     return {
         "version": __version__,