Notebook to sphinx-gallery script

dev/ipynb_to_gallery.py

@@ -0,0 +1,63 @@
+"""
+This python script is inspired from https://gist.github.com/chsasank/7218ca16f8d022e02a9c0deb94a310fe .
+
+Convert jupyter notebook to sphinx gallery python script.
+
+Usage: python ipynb_to_gallery.py <notebook.ipynb> (Optional)<output.py>
+"""
+import json
+import pypandoc as pdoc
+
+
+def convert_ipynb_to_gallery(input_file_name, output_file_name=None):
+    """
+    Convert jupyter notebook to sphinx gallery python script.
+
+    parameters
+    ----------
+    input_file_name: str
+        Path to the jupyter notebook file.
+    output_file_name: str
+        Path to the output python file. If not provided, the output file name is the same as the input file name.
+    """
+    python_file = ""
+
+    nb_dict = json.load(open(input_file_name))
+    cells = nb_dict["cells"]
+
+    for i, cell in enumerate(cells):
+        if i == 0:
+            assert cell["cell_type"] == "markdown", "First cell has to be markdown"
+
+            md_source = "".join(cell["source"])
+            rst_source = pdoc.convert_text(md_source, "rst", "md")
+            python_file = '"""\n' + rst_source + '\n"""'
+        else:
+            if cell["cell_type"] == "markdown":
+                md_source = "".join(cell["source"])
+                rst_source = pdoc.convert_text(md_source, "rst", "md")
+                commented_source = "\n".join(["# " + x for x in rst_source.split("\n")])
+                python_file = (
+                    python_file + "\n\n\n" + "#" * 70 + "\n" + commented_source
+                )
+            elif cell["cell_type"] == "code":
+                source = "".join(cell["source"])
+                python_file = python_file + "\n" * 2 + source
+
+    python_file = python_file.replace("\n%", "\n# %")
+    if output_file_name is None:
+        output_file_name = input_file_name
+        open(output_file_name.replace(".ipynb", ".py"), "w").write(python_file)
+    else:
+        if not output_file_name.endswith(".py"):
+            output_file_name = output_file_name + ".py"
+        open(output_file_name.write(python_file))
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) > 2:
+        convert_ipynb_to_gallery(sys.argv[-2], sys.argv[-1])
+    else:
+        convert_ipynb_to_gallery(sys.argv[-1])

docs/development/dev_howto.rst

@@ -939,3 +939,17 @@ Nearly all base classes in Gammapy implement this default
 a default implementation is not needed, since it will rely on its
 (grand)parent. As a result, for specific HTML output, only the
 `to_html` method needs to be implented for the relevant class.
+
+Convert a jupyter notebook to python script in the sphinx-gallery format
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The tutorials in Gammapy are represented by python scripts written in the sphinx-gallery format. However, since they are
+displayed as jupyter notebooks in the documentation,
+it is usually easier to first create a tutorial in a jupyter notebook and then convert
+it into a python script. This can be done using ``ipynb_to_gallery.py`` script located in the ``dev`` folder. This
+script can be used as follows::
+
+    python dev/ipynb_to_gallery.py <path_to_notebook> (Optional)<path_to_script>
+
+If the path of the output file is not provided, the script will be written in the same folder as the notebook and with
+the same name.

environment-dev.yml

@@ -81,3 +81,4 @@ dependencies:
       - pytest-sphinx
       - ray
       - PyGithub
+      - pypandoc