From 361eecf58cdb27f45f315e14ff8401b24649373a Mon Sep 17 00:00:00 2001 From: Mohammad Amin Tahavori <50955527+mohammadamint@users.noreply.github.com> Date: Fri, 1 Dec 2023 23:07:57 +0100 Subject: [PATCH 1/4] creating a script to automatize the conversion of jupyter files to rst when an example is updated in jupyter notebook files, the script can be used to automatically convert the jupyter files in notebooks folder to rst files saved to source/examples for the documentaiton changes: 1. docs/notebooks_convert.py: the script to read the jupyter files, convert them to rst and save them into example folder 2. docs-requirements.py: updating the requirements with nbformat and nbconvert needed for the conversion --- docs/docs-requirements.txt | 2 ++ docs/notebooks_convert.py | 52 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 docs/notebooks_convert.py diff --git a/docs/docs-requirements.txt b/docs/docs-requirements.txt index 21d2eba4..4259dc0b 100644 --- a/docs/docs-requirements.txt +++ b/docs/docs-requirements.txt @@ -15,3 +15,5 @@ sphinx-pdj-theme # TODO to comment sphinx-copybutton sphinxjp.themes.sphinxjp sphinxjp.themes.basicstrap +nbformat +nbconvert diff --git a/docs/notebooks_convert.py b/docs/notebooks_convert.py new file mode 100644 index 00000000..42cd60b4 --- /dev/null +++ b/docs/notebooks_convert.py @@ -0,0 +1,52 @@ +from nbconvert import RSTExporter +from nbconvert.writers import FilesWriter +import nbformat +import os + +path = os.path.abspath( + os.path.join( + os.path.dirname(__file__), + ) +) +def convert_notebook_to_rst(input_file, output_dir,file_name): + # Load the notebook + with open(input_file, 'r', encoding='utf-8') as f: + notebook_content = nbformat.read(f, as_version=4) + + # Create an RST exporter + rst_exporter = RSTExporter() + + # Generate RST content + rst_content, resources = rst_exporter.from_notebook_node(notebook_content) + + if not os.path.exists(output_dir): + os.mkdir(output_dir) + + output_file = f"{output_dir}/{file_name}.rst" + + # Write RST content to the output file + with open(output_file, 'w', encoding='utf-8') as f: + f.write(rst_content) + + print(f"Conversion successful. RST file saved to: {output_file}") + + # Copy images to the output folder + image_dir = output_dir + for image_filename, image_data in resources['outputs'].items(): + image_path = f"{output_dir}/{image_filename}" + with open(image_path, 'wb') as img_file: + img_file.write(image_data) + +def get_all_ipynb_files(examples_path="notebooks"): + + all_files = os.listdir(examples_path) + return [(f"{path}/{examples_path}/{file}",file.split(".ipynb")[0]) for file in all_files if file.endswith("ipynb")] + + +if __name__ == "__main__": + + files = get_all_ipynb_files() + + for file,folder in files: + convert_notebook_to_rst(file, f"{path}/source/examples/{folder}",folder) + From 442fdcbbab6e890b91d961bf4174ad4623cc2e0b Mon Sep 17 00:00:00 2001 From: Mohammad Amin Tahavori <50955527+mohammadamint@users.noreply.github.com> Date: Fri, 1 Dec 2023 23:19:29 +0100 Subject: [PATCH 2/4] lint notebooks_converter.py script --- docs/notebooks_convert.py | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/notebooks_convert.py b/docs/notebooks_convert.py index 42cd60b4..c2295294 100644 --- a/docs/notebooks_convert.py +++ b/docs/notebooks_convert.py @@ -3,14 +3,12 @@ import nbformat import os -path = os.path.abspath( - os.path.join( - os.path.dirname(__file__), - ) -) -def convert_notebook_to_rst(input_file, output_dir,file_name): +path = os.path.abspath(os.path.join(os.path.dirname(__file__),)) + + +def convert_notebook_to_rst(input_file, output_dir, file_name): # Load the notebook - with open(input_file, 'r', encoding='utf-8') as f: + with open(input_file, "r", encoding="utf-8") as f: notebook_content = nbformat.read(f, as_version=4) # Create an RST exporter @@ -25,28 +23,32 @@ def convert_notebook_to_rst(input_file, output_dir,file_name): output_file = f"{output_dir}/{file_name}.rst" # Write RST content to the output file - with open(output_file, 'w', encoding='utf-8') as f: + with open(output_file, "w", encoding="utf-8") as f: f.write(rst_content) print(f"Conversion successful. RST file saved to: {output_file}") # Copy images to the output folder image_dir = output_dir - for image_filename, image_data in resources['outputs'].items(): + for image_filename, image_data in resources["outputs"].items(): image_path = f"{output_dir}/{image_filename}" - with open(image_path, 'wb') as img_file: + with open(image_path, "wb") as img_file: img_file.write(image_data) + def get_all_ipynb_files(examples_path="notebooks"): all_files = os.listdir(examples_path) - return [(f"{path}/{examples_path}/{file}",file.split(".ipynb")[0]) for file in all_files if file.endswith("ipynb")] + return [ + (f"{path}/{examples_path}/{file}", file.split(".ipynb")[0]) + for file in all_files + if file.endswith("ipynb") + ] if __name__ == "__main__": files = get_all_ipynb_files() - for file,folder in files: - convert_notebook_to_rst(file, f"{path}/source/examples/{folder}",folder) - + for file, folder in files: + convert_notebook_to_rst(file, f"{path}/source/examples/{folder}", folder) From 8d39969eaddfc6dccd64e2a29c6d83708816f24b Mon Sep 17 00:00:00 2001 From: Mohammad Amin Tahavori <50955527+mohammadamint@users.noreply.github.com> Date: Sat, 2 Dec 2023 00:31:54 +0100 Subject: [PATCH 3/4] Apply suggestions from code review replacing f"{}/{}" with ps.path.join Co-authored-by: Pierre Francois --- docs/notebooks_convert.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/notebooks_convert.py b/docs/notebooks_convert.py index c2295294..6b47812a 100644 --- a/docs/notebooks_convert.py +++ b/docs/notebooks_convert.py @@ -20,7 +20,7 @@ def convert_notebook_to_rst(input_file, output_dir, file_name): if not os.path.exists(output_dir): os.mkdir(output_dir) - output_file = f"{output_dir}/{file_name}.rst" + output_file = os.path.join(output_dir, f"{{file_name}.rst") # Write RST content to the output file with open(output_file, "w", encoding="utf-8") as f: @@ -31,7 +31,7 @@ def convert_notebook_to_rst(input_file, output_dir, file_name): # Copy images to the output folder image_dir = output_dir for image_filename, image_data in resources["outputs"].items(): - image_path = f"{output_dir}/{image_filename}" + image_path = os.path,join(output_dir, image_filename) with open(image_path, "wb") as img_file: img_file.write(image_data) @@ -40,7 +40,7 @@ def get_all_ipynb_files(examples_path="notebooks"): all_files = os.listdir(examples_path) return [ - (f"{path}/{examples_path}/{file}", file.split(".ipynb")[0]) + (os.path.join(path, examples_path, file), file.split(".ipynb")[0]) for file in all_files if file.endswith("ipynb") ] @@ -51,4 +51,4 @@ def get_all_ipynb_files(examples_path="notebooks"): files = get_all_ipynb_files() for file, folder in files: - convert_notebook_to_rst(file, f"{path}/source/examples/{folder}", folder) + convert_notebook_to_rst(file, os.path.join(path, source, examples,folder), folder) From dd13fc6e577740bb4e02a6a1470abdf12f412f33 Mon Sep 17 00:00:00 2001 From: Mohammad Amin Tahavori <50955527+mohammadamint@users.noreply.github.com> Date: Sat, 2 Dec 2023 01:12:57 +0100 Subject: [PATCH 4/4] linting --- docs/notebooks_convert.py | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/notebooks_convert.py b/docs/notebooks_convert.py index 6b47812a..60a491c1 100644 --- a/docs/notebooks_convert.py +++ b/docs/notebooks_convert.py @@ -3,7 +3,11 @@ import nbformat import os -path = os.path.abspath(os.path.join(os.path.dirname(__file__),)) +path = os.path.abspath( + os.path.join( + os.path.dirname(__file__), + ) +) def convert_notebook_to_rst(input_file, output_dir, file_name): @@ -20,7 +24,7 @@ def convert_notebook_to_rst(input_file, output_dir, file_name): if not os.path.exists(output_dir): os.mkdir(output_dir) - output_file = os.path.join(output_dir, f"{{file_name}.rst") + output_file = os.path.join(output_dir, f"{file_name}.rst") # Write RST content to the output file with open(output_file, "w", encoding="utf-8") as f: @@ -31,13 +35,12 @@ def convert_notebook_to_rst(input_file, output_dir, file_name): # Copy images to the output folder image_dir = output_dir for image_filename, image_data in resources["outputs"].items(): - image_path = os.path,join(output_dir, image_filename) + image_path = os.path.join(output_dir, image_filename) with open(image_path, "wb") as img_file: img_file.write(image_data) def get_all_ipynb_files(examples_path="notebooks"): - all_files = os.listdir(examples_path) return [ (os.path.join(path, examples_path, file), file.split(".ipynb")[0]) @@ -47,8 +50,9 @@ def get_all_ipynb_files(examples_path="notebooks"): if __name__ == "__main__": - files = get_all_ipynb_files() for file, folder in files: - convert_notebook_to_rst(file, os.path.join(path, source, examples,folder), folder) + convert_notebook_to_rst( + file, os.path.join(path, "source", "examples", folder), folder + )