[DOC] Code cells are not copyable easily

[dhruvbalwada]

What were you looking for/trying to do?:
Often when working through examples in the documentation we want to copy code any play with it.

What was missing from the docs or not clear enough?:
However the way code cells are currently rendered there is no easy way to do a copy (we can literally type things out, or copy the whole thing over and then get rid of the line numbers and ... etc).

How could the docs be improved? Additional examples, different wording, etc.
Renderering copyable code cells would be great, one example is here: https://m2lines.github.io/L96_demo/notebooks/L96-two-scale-description.html (which was achieved by @IamShubhamGupto). Wondering if doing the switch is easy?

[IamShubhamGupto]

Hey @dhruvbalwada

I would be happy to help you out with this. I just glanced over XGCMs code blocks and they seem to have line numbers enabled, and have input output on the same block. This makes it hard to copy paste the code.

I did not see a similar setup the L96_demo where we had a _config.yml. Im guessing some setting file would be similar to achieve what youre looking for.

cc @jbusecke if maybe you can point us in the right direction

[IamShubhamGupto]

@jbusecke bumping this up in notifications

[IamShubhamGupto]

@dhruvbalwada @jbusecke

Some progress today after setting up the docs locally, we need to setup the data locally too if we're going to compile during build

Please help me find the data used by all tutorials, thanks

[IamShubhamGupto]

I achieved this by making 2 changes

1. updated sphinx to the latest version - don't think this helped
2. changed all cells to code block and told nbshphinx to always execute

[jbusecke]

Thanks for all the work here @IamShubhamGupto.

Can you make a PR with these changes to the repo so we can discuss the changes in more detail? I believe RTD should generate a preview of the docs on PRs so we can check how your changes would affect the actual outcome.

Some progress today after setting up the docs locally, we need to setup the data locally too if we're going to compile during build

If you could add the way you set this up locally to our contributor guide that would be very helpful.

[IamShubhamGupto]

@jbusecke it'll be ready in the next couple of days, from my experiments, I cannot execute code with separated code blocks like in https://m2lines.github.io/L96_demo/intro.html from rst files.

It might be a limitation of documentation type. Instead I will be converting them to .ipynb files.

Also could you help me find ../datasets/mitgcm_example_dataset_v2.nc used by grid_metrics?thanks

[jbusecke]

Also could you help me find ../datasets/mitgcm_example_dataset_v2.nc used by grid_metrics?

I think you might have caught a long standing bug here (quick look up makes me think that the dataset is the same as in https://xgcm.readthedocs.io/en/latest/xgcm-examples/02_mitgcm.html). But this exposes a bigger issue:
We actually do not execute our code on build, but we clearly should.

I cannot execute code with separated code blocks like in https://m2lines.github.io/L96_demo/intro.html from rst files.

I am fairly sure that you can do that with sphinx somehow (maybe it requires an extension). But maybe your intuition is right here, more on that below. In general we should be able to provide a mix of notebooks, md, rst files and have them all execute code?

Instead I will be converting them to .ipynb files.

I am not 100% sure if converting the entire docs page to notebooks is the right way forward (yet), but your suggestion of modernizing the docs would certainly be very welcome! I suggest we start with an issue that enumerates all the docs related past issues and then think about a way forward? To set expectations a bit. I think this is a larger project since there are likely a bunch more of these (#573 for example) hiding in the docs.

Again thank you so much for putting in the time here, I really appreciate this!

[IamShubhamGupto]

Hey @jbusecke I experimented with the following packages hoping to execute python same as Jupyter notebooks do it, unfortunately none gave the desired result

I am fairly sure that you can do that with sphinx somehow (maybe it requires an extension). But maybe your intuition is right here, more on that below. In general we should be able to provide a mix of notebooks, md, rst files and have them all execute code?

• https://pypi.org/project/sphinx-autorun/
• https://yongrenjie.github.io/sphinx-exec-directive/ - looked promising, but just did not render any of the code blocks in the final html
• doctest

I might be hyper focused here and might have missed something so I'll retry after some time.

Converting to ipynb is not the most elegant solution, its just something im familiar with.

Instead I will be converting them to .ipynb files.

I am not 100% sure if converting the entire docs page to notebooks is the right way forward (yet), but your suggestion of modernizing the docs would certainly be very welcome! I suggest we start with an issue that enumerates all the docs related past issues and then think about a way forward? To set expectations a bit. I think this is a larger project since there are likely a bunch more of these (#573 for example) hiding in the docs.

Ill debug this for now and come back issue to this soon