Notebook to sphinx-gallery script

[MRegeard]

This PR is related to issue #4441.

It adds a script in the dev folder that allows to convert jupyter notebook in the sphinx-gallery python script format. This is especially useful when creating a tutorial. First create it as a jupyter notebook, and them convert it into a python script when the tutorial is ready to be reviewed.

This PR also adds a small section in the dev how-to documentation that explain how to use this script.

Since this script uses pypandoc, I also added pypandoc to the pip section of the environment file. This is not a big deal because we already have pandoc in the environment file and pypandoc is just a python wrapper for pandoc.
I put it in the pip section because it is not available for os-arm in the conda-forge repository.

[codecov]

Codecov Report

Merging #4854 (ec2f774) into main (d811f92) will decrease coverage by 0.02%.
Report is 24 commits behind head on main.
The diff coverage is 37.50%.

@@            Coverage Diff             @@
##             main    #4854      +/-   ##
==========================================
- Coverage   75.63%   75.62%   -0.02%     
==========================================
  Files         226      226              
  Lines       33029    33069      +40     
==========================================
+ Hits        24983    25007      +24     
- Misses       8046     8062      +16     

Files	Coverage Δ
gammapy/modeling/models/core.py	84.45% <33.33%> (-0.30%)	⬇️
gammapy/modeling/models/tests/test_core.py	76.60% <38.46%> (-3.14%)	⬇️

... and 13 files with indirect coverage changes

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[bkhelifi]

Thanks @MRegeard...
A naive question: have you try to take a notebook build by our doc (e.g. docs/tutorials/api/makers.ipynb) and compare the output of this code to the initial python code?

[MRegeard]

@bkhelifi, Yes I checked that !

The only thing that is different is that it put =====under the "title" of the notebook while it is currently ----- in our notebooks. But I checked and it does not affect the rendering on the documentation.

The other thing that it was doing was adding a

"`"

at the beginning and at the end when we made reference to the code using ~gammapy.*, even though one was already there. That's why I added a replace("``", "`") after generating the string.

Tell me if anyone has a strong opinion on the `====, I will find a way !

[AtreyeeS]

Thank you for this much needed addition.

Maybe you can build the docs locally on your machine once to ensure that the rendered notebooks have no issues with the ====

[MRegeard]

@AtreyeeS, That's what I have done ! So it does not change anything, at least that I could notice.

But I just notice that we are using indistinctly ==== and ----- for the "title" of the tutorial. So we might want to uniform that anyway.

[Astro-Kirsty]

Thanks @MRegeard.
Just made some minor comments!

[registerrier]

Thanks @MRegeard . This is very useful!

I have left a few minor comments inline.

[registerrier]

Suggested change

	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, "w").write(python_file)
	if output_file_name is None:
	output_file_name = input_file_name.replace(".ipynb", ".py")
	if not output_file_name.endswith(".py"):
	output_file_name = output_file_name + ".py"
	open(output_file_name, "w").write(python_file)

less indentation is usually better

[registerrier]

Note that you could also use the gammapy.utils.script.make_path function which allows you to use pathlib.Path objects with e.g. Path.write_text(python_file) or Path.with_suffix(".py")

[MRegeard]

Yes it's true that I could have used that.
Now that it is written like this, do you see any reason why we should switch to Path?

[MRegeard]

@registerrier, @Astro-Kirsty, suggestion implemented !

[bkhelifi]

Thanks @MRegeard.. From my side, nothing more to add