From 15f58f5e62089579a4dc83698f1049aa5c9d5b05 Mon Sep 17 00:00:00 2001 From: Cristian Lara Date: Fri, 22 Nov 2024 14:47:33 -0600 Subject: [PATCH 1/3] [Tutorials] Fix github links The file structure was previously modified so that each tutorial is nested within a folder of the same name. --- scripts/convert_ipynb_to_mdx.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/convert_ipynb_to_mdx.py b/scripts/convert_ipynb_to_mdx.py index 36609f9f4af..c924361129c 100644 --- a/scripts/convert_ipynb_to_mdx.py +++ b/scripts/convert_ipynb_to_mdx.py @@ -172,7 +172,7 @@ def create_buttons( Returns: str: MDX formatted buttons. """ - github_url = f"https://github.com/cristianlara/Ax/blob/main/tutorials/{nb_metadata['id']}.ipynb" + github_url = f"https://github.com/cristianlara/Ax/blob/main/tutorials/{nb_metadata['id']}/{nb_metadata['id']}.ipynb" colab_url = f"https://colab.research.google.com/github/cristianlara/Ax/blob/main/tutorials/{nb_metadata['id']}/{nb_metadata['id']}.ipynb" return f'\n\n' From 0eb2a431ffb021f2437f3677351221bf3ea2fb2e Mon Sep 17 00:00:00 2001 From: Cristian Lara Date: Fri, 22 Nov 2024 15:36:32 -0600 Subject: [PATCH 2/3] [Tutorials] Github and Colab links point to the correct version matching the currently viewed tutorial Instead of storing each version of the tutorials in docusaurus, we can just link to the tagged version in our github repo. This will save us a lot of space when building and deploying the website. --- scripts/convert_ipynb_to_mdx.py | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/scripts/convert_ipynb_to_mdx.py b/scripts/convert_ipynb_to_mdx.py index c924361129c..990fc702acd 100644 --- a/scripts/convert_ipynb_to_mdx.py +++ b/scripts/convert_ipynb_to_mdx.py @@ -7,10 +7,11 @@ import json import re import shutil +import subprocess import uuid import io from pathlib import Path -from typing import Any, Dict, List, Tuple, Union +from typing import Any, Dict, List, Tuple, Union, Optional import mdformat # @manual=fbsource//third-party/pypi/mdformat:mdformat import nbformat @@ -156,24 +157,35 @@ def create_imports() -> str: return f"{imports}\n" +def get_current_git_tag() -> Optional[str]: + """ + Retrieve the current Git tag if the current commit is tagged. + + Returns: + Optional[str]: The current Git tag as a string if available, otherwise None. + """ + try: + tag = subprocess.check_output(['git', 'describe', '--tags', '--exact-match'], stderr=subprocess.STDOUT).strip().decode('utf-8') + return tag + except subprocess.CalledProcessError: + return None + + def create_buttons( nb_metadata: Dict[str, Dict[str, str]], - tutorial_folder_name: str, ) -> str: """ Create buttons that link to Colab and GitHub for the tutorial. Args: nb_metadata (Dict[str, Dict[str, str]]): Metadata for the tutorial. - tutorial_folder_name (str): The name of the tutorial folder where the MDX - converted files exist. This is typically just the name of the Jupyter - notebook file. Returns: str: MDX formatted buttons. """ - github_url = f"https://github.com/cristianlara/Ax/blob/main/tutorials/{nb_metadata['id']}/{nb_metadata['id']}.ipynb" - colab_url = f"https://colab.research.google.com/github/cristianlara/Ax/blob/main/tutorials/{nb_metadata['id']}/{nb_metadata['id']}.ipynb" + version = get_current_git_tag() or "main" + github_url = f"https://github.com/cristianlara/Ax/blob/{version}/tutorials/{nb_metadata['id']}/{nb_metadata['id']}.ipynb" + colab_url = f"https://colab.research.google.com/github/cristianlara/Ax/blob/{version}/tutorials/{nb_metadata['id']}/{nb_metadata['id']}.ipynb" return f'\n\n' @@ -966,7 +978,7 @@ def transform_notebook(path: Path, nb_metadata: object) -> str: mdx = "" mdx += create_frontmatter(path, nb_metadata) mdx += create_imports() - mdx += create_buttons(nb_metadata, path.stem) + mdx += create_buttons(nb_metadata) for cell in nb["cells"]: cell_type = cell["cell_type"] From cfa6fb5fe808968fdd4aba12ea1cd1fa0df54071 Mon Sep 17 00:00:00 2001 From: Cristian Lara Date: Fri, 22 Nov 2024 15:39:12 -0600 Subject: [PATCH 3/3] [Tutorials] Only delete directories on --clean argument Letting a script delete files on your filesystem is scary, let's make it optional --- scripts/convert_ipynb_to_mdx.py | 29 +++++++++++++++++++++++------ scripts/make_docs.sh | 2 +- 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/scripts/convert_ipynb_to_mdx.py b/scripts/convert_ipynb_to_mdx.py index 990fc702acd..a14c0566c9a 100644 --- a/scripts/convert_ipynb_to_mdx.py +++ b/scripts/convert_ipynb_to_mdx.py @@ -10,6 +10,7 @@ import subprocess import uuid import io +import argparse from pathlib import Path from typing import Any, Dict, List, Tuple, Union, Optional @@ -999,17 +1000,33 @@ def transform_notebook(path: Path, nb_metadata: object) -> str: return mdx +def clean_up_directories() -> None: + """ + Delete output from previously converted notebooks. Particularly useful for + removing plot data since those filenames are randomly generated and won't + be replaced with future runs. + + Returns: + None: Does not return anything. + """ + if TUTORIALS_DIR.exists(): + # We intentionally leave the static `index.mdx` file in place since that is not autogenerated. + for item in os.scandir(TUTORIALS_DIR): + if item.is_dir(): + shutil.rmtree(item.path) + + if __name__ == "__main__": + parser = argparse.ArgumentParser(description="Convert tutorial notebooks into mdx files.") + parser.add_argument("--clean", action='store_true', help="Delete output from previously converted notebooks.") + args = parser.parse_args() + tutorials_metadata = load_nb_metadata() print("--------------------------------------------") print("Converting tutorial notebooks into mdx files") print("--------------------------------------------") - if TUTORIALS_DIR.exists(): - # Remove previous tutorial docs if any. We intentionally leave the - # static `index.mdx` file in place since that is not autogenerated. - for item in os.scandir(TUTORIALS_DIR): - if item.is_dir(): - shutil.rmtree(item.path) + if args.clean: + clean_up_directories() for metadata in tutorials_metadata: path = (LIB_DIR / "tutorials" / metadata["id"] / (metadata["id"] + ".ipynb")).resolve() print(f"{path.stem}") diff --git a/scripts/make_docs.sh b/scripts/make_docs.sh index 7640c13e37c..357afd1e284 100755 --- a/scripts/make_docs.sh +++ b/scripts/make_docs.sh @@ -52,7 +52,7 @@ if [[ $ONLY_DOCUSAURUS == false ]]; then echo "-----------------------------------" echo "Generating tutorials" echo "-----------------------------------" - python3 scripts/convert_ipynb_to_mdx.py + python3 scripts/convert_ipynb_to_mdx.py --clean fi # end of not only Docusaurus block