Use "# %%" as code block separators in examples #2662

yvonnefroehlich · 2023-09-04T12:36:10Z

Description of proposed changes

This PR aims to replace the code block separator ############################################################################### by # %% and also add this separator at thte beginning of the code:

Gallery examples
Tutorials
Intros
Projections

Fixes #2660

Preview: https://pygmt-dev--2662.org.readthedocs.build/en/2662/tutorials/basics/coastlines.html

Reminders

Run make format and make check to make sure the code follows the style guide.
Add tests for new features or tests that would have caught the bug that you're fixing.
Add new public functions/methods/classes to doc/api/index.rst.
Write detailed docstrings for all functions/methods.
If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
If adding new functionality, add an example to docstrings or tutorials.
Use underscores (not hyphens) in names of Python files and directories.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

/format: automatically format and lint the code
/test-gmt-dev: run full tests on the latest GMT development version

yvonnefroehlich · 2023-09-04T13:12:09Z

/format

seisman · 2023-09-07T06:56:23Z

Something doesn't work as expected (e.g., https://pygmt-dev--2662.org.readthedocs.build/en/2662/tutorials/basics/coastlines.html):

yvonnefroehlich · 2023-09-07T08:54:17Z

Something doesn't work as expected (e.g., https://pygmt-dev--2662.org.readthedocs.build/en/2662/tutorials/basics/coastlines.html):

This issue occurs in examples in which we use # sphinx_gallery_thumbnail_number = x.
In commit d375ec5 I changed the order from

"""

# sphinx_gallery_thumbnail_number = x

# %%
import pygmt

to

"""

# %%

# sphinx_gallery_thumbnail_number = x
import pygmt

Then the output looks correct:

seisman · 2023-09-08T00:39:06Z

Still WIP?

yvonnefroehlich · 2023-09-08T06:07:54Z

Still WIP?

Should be ready for review 🙂.

seisman · 2023-09-09T01:12:54Z

examples/tutorials/basics/regions.py

@@ -74,7 +73,8 @@
 )
 fig.show()



The number of blank lines above the # %% separator is inconsistent. For example, there is only one blank line near line 56, but two blank lines near line 77. Maybe we should have only one blank line above # %%, although it really doesn't matter much.

This is because there are two blank lines in case of a following subsection, otherwise only one blank is used. This is the concept in some of the tutorials. For me, this makes it easier to read the script, because it gives a bit more structure, especially for longer ones. Thus, I tried / decided to use this consistently across all examples. But as you mentioned, this doesn't matter much, I can change it to have only one blank line before subsections.

This is because there are two blank lines in case of a following subsection, otherwise only one blank is used.

OK. That makes sense to me.

seisman · 2023-09-09T01:27:14Z

In commit d375ec5 I changed the order from

"""

# sphinx_gallery_thumbnail_number = x

# %%
import pygmt

to

"""

# %%

# sphinx_gallery_thumbnail_number = x
import pygmt

I had a quick look at the Sphinx-Gallery source code. It seems that anything between the docstring and the first # %% separator is thought as "code". In this case, # sphinx_gallery_thumbnail_number = x will be shown in a code block, but it's also removed because we have remove_config_comments to True in conf.py. That's why we see an empty code block.

Your fix in d375ec5 works as expected, but the biggest limitation is that there must be a blank line between # sphinx_gallery_thumbnail_number = x and # %%.

I think it makes more sense to have # sphinx_gallery_thumbnail_number = x at the end of each script, and it seems work well.

yvonnefroehlich · 2023-09-09T06:59:52Z

I had a quick look at the Sphinx-Gallery source code. It seems that anything between the docstring and the first # %% separator is thought as "code". In this case, # sphinx_gallery_thumbnail_number = x will be shown in a code block, but it's also removed because we have remove_config_comments to True in conf.py. That's why we see an empty code block.

Your fix in d375ec5 works as expected, but the biggest limitation is that there must be a blank line between # sphinx_gallery_thumbnail_number = x and # %%.

Yes, you are completly right! I was / am also not happy with this blank line. But as I tried several sequences at the beginning of the code and only the one in commit d375ec5 worked without producing an empty code block, I accepted the blank line.

I think it makes more sense to have # sphinx_gallery_thumbnail_number = x at the end of each script, and it seems work well.

I am fine with this solution and can change it later the day. If we go with this solution, I should probably also submit a PR to update the Contributors Guide at https://www.pygmt.org/dev/contributing.html#contributing-tutorials.

…llery

yvonnefroehlich · 2023-09-09T10:18:20Z

I think it makes more sense to have # sphinx_gallery_thumbnail_number = x at the end of each script, and it seems work well.

I am fine with this solution and can change it later the day.

This is done in the commits 2a9c466, d3d5b3b, and d24a45c.

If we go with this solution, I should probably also submit a PR to update the Contributors Guide at https://www.pygmt.org/dev/contributing.html#contributing-tutorials.

Please see PR #2675 for this update.

seisman

Look good to me.

yvonnefroehlich added 26 commits September 4, 2023 14:05

Update code block separator in example 'timestamp.py'

b0c847b

Update code block separator in example 'rgb_image.py'

f8967c3

Update code block separator in example 'quoted_lines.py'

95f4b64

Update code block separator in example 'country_polygons.py'

52ceba7

Update code block separator in example 'tilemaps.py'

216b25a

Update code block separator in example 'multi_parameter_symbols.py'

ff4405a

Update code block separator in intro '01_first_figure.py'

0ddc58a

Update code block separator in intro '02_contour_map.py'

4cf0c8e

Update code block separator in tutorial 'coastlines.py'

2a3e9b0

Update code block separator in tutorial 'frames.py'

22ce481

Update code block separator in tutorial 'lines.py'

b97760c

Update code block separator in tutorial 'plot.py'

a20980f

Update code block separator in tutorial 'regions.py'

0dee6d9

Update code block separator in tutorial 'text.py'

56e1f91

Update code block separator in tutorial 'insets.py'

b09e0fd

Update code block separator in tutorial 'vectors.py'

b6c1e3a

Update code block separator in tutorial 'cartesian_histograms.py'

9e98491

Update code block separator in tutorial 'working_with_panel.py'

03fbd7e

Update code block separator in tutorial 'date_time_charts.py'

af43904

Update code block separator in tutorial 'contour_map.py'

a366801

Update code block separator in tutorial '3d_perspective_image.py'

1818644

Update code block separator in tutorial 'earth_relief.py'

bc1991e

Update code block separator in tutorial 'configuration.py'

d33671b

Update code block separator in tutorial 'grid_equalization.py'

39d9d75

Update code block separator in tutorial 'subplots.py'

c11feb2

Use two empty lines before subsections

4544663

[format-command] fixes

4f694ac

yvonnefroehlich self-assigned this Sep 4, 2023

yvonnefroehlich added the maintenance Boring but important stuff for the core devs label Sep 4, 2023

Use 'correct' order in case 'sphinx_gallery_thumbnail_number' is used

d375ec5

yvonnefroehlich changed the title ~~WIP: Update code block separators to "# %%"~~ Update code block separators to "# %%" Sep 8, 2023

yvonnefroehlich added 2 commits September 8, 2023 07:57

Remove blank line

c2bf93e

Add blank lines

ed85e0a

yvonnefroehlich added the needs review This PR has higher priority and needs review. label Sep 8, 2023

seisman reviewed Sep 9, 2023

View reviewed changes

yvonnefroehlich added 4 commits September 9, 2023 10:47

Move 'sphinx_gallery_thumbnail_number' to the end of the script

2a9c466

Move 'sphinx_gallery_thumbnail_number' to the end of the script in ga…

d3d5b3b

…llery

Move 'sphinx_gallery_thumbnail_number' to the end of the script in ga…

d24a45c

…llery

Update codeblock separator in 'azim' projections

de695a1

yvonnefroehlich mentioned this pull request Sep 9, 2023

Update Contributors Guide regarding position of the thumbnail figure comment #2675

Merged

7 tasks

seisman approved these changes Sep 9, 2023

View reviewed changes

seisman changed the title ~~Update code block separators to "# %%"~~ Update code block separators to "# %%" in gallery examples Sep 9, 2023

yvonnefroehlich mentioned this pull request Sep 9, 2023

Update README for the "Intro to PyGMT" #2678

Merged

7 tasks

seisman added final review call This PR requires final review and approval from a second reviewer and removed skip-changelog Skip adding Pull Request to changelog needs review This PR has higher priority and needs review. labels Sep 10, 2023

seisman changed the title ~~Update code block separators to "# %%" in gallery examples~~ Update code block separators to "# %%" in examples Sep 10, 2023

seisman merged commit 5546573 into main Sep 10, 2023
8 checks passed

seisman deleted the update-codeblock-separators branch September 10, 2023 10:11

seisman changed the title ~~Update code block separators to "# %%" in examples~~ Use "# %%" as code block separators in examples Sep 10, 2023

seisman removed the final review call This PR requires final review and approval from a second reviewer label Sep 10, 2023

yvonnefroehlich mentioned this pull request Nov 11, 2023

Gallery example "choropleth map": Use code block separator "# %%" #2805

Merged

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use "# %%" as code block separators in examples #2662

Use "# %%" as code block separators in examples #2662

yvonnefroehlich commented Sep 4, 2023 •

edited

Loading

yvonnefroehlich commented Sep 4, 2023

seisman commented Sep 7, 2023

yvonnefroehlich commented Sep 7, 2023 •

edited

Loading

seisman commented Sep 8, 2023

yvonnefroehlich commented Sep 8, 2023

seisman Sep 9, 2023 •

edited

Loading

yvonnefroehlich Sep 9, 2023

seisman Sep 9, 2023

seisman commented Sep 9, 2023

yvonnefroehlich commented Sep 9, 2023 •

edited

Loading

yvonnefroehlich commented Sep 9, 2023

seisman left a comment

Use "# %%" as code block separators in examples #2662

Use "# %%" as code block separators in examples #2662

Conversation

yvonnefroehlich commented Sep 4, 2023 • edited Loading

yvonnefroehlich commented Sep 4, 2023

seisman commented Sep 7, 2023

yvonnefroehlich commented Sep 7, 2023 • edited Loading

seisman commented Sep 8, 2023

yvonnefroehlich commented Sep 8, 2023

seisman Sep 9, 2023 • edited Loading

Choose a reason for hiding this comment

yvonnefroehlich Sep 9, 2023

Choose a reason for hiding this comment

seisman Sep 9, 2023

Choose a reason for hiding this comment

seisman commented Sep 9, 2023

yvonnefroehlich commented Sep 9, 2023 • edited Loading

yvonnefroehlich commented Sep 9, 2023

seisman left a comment

Choose a reason for hiding this comment

yvonnefroehlich commented Sep 4, 2023 •

edited

Loading

yvonnefroehlich commented Sep 7, 2023 •

edited

Loading

seisman Sep 9, 2023 •

edited

Loading

yvonnefroehlich commented Sep 9, 2023 •

edited

Loading