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

@@ -15,3 +15,5 @@ sphinx-pdj-theme # TODO to comment
 sphinx-copybutton
 sphinxjp.themes.sphinxjp
 sphinxjp.themes.basicstrap
+nbformat
+nbconvert

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)
+