Add Figure.paragraph to typeset one or multiple paragraph of text strings

[seisman]

Initial implementation for the Figure.paragraph method, which wraps the text module's -M option.

Related to #3710.

Preview:

• https://pygmt-dev--3709.org.readthedocs.build/en/3709/api/generated/pygmt.Figure.paragraph.html
• https://pygmt-dev--3709.org.readthedocs.build/en/3709/api/generated/pygmt.Figure.text.html

Example

import pygmt

fig = pygmt.Figure()
fig.basemap(region=[0, 10, 0, 10], projection="X10c/10c", frame=True)
fig.paragraph(
    x=4,
    y=4,
    text="This is a long paragraph. " * 10,
    parwidth="5c",
    linespacing="12p",
    font="12p",
)
fig.show()

[github-actions]

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
added	pygmt/tests/baseline/test_paragraph.png
added	pygmt/tests/baseline/test_paragraph_multiple_paragraphs_blankline.png
added	pygmt/tests/baseline/test_paragraph_multiple_paragraphs_list.png

Image diff(s)

Details

Added images

• test_paragraph.png

• test_paragraph_multiple_paragraphs_blankline.png

• test_paragraph_multiple_paragraphs_list.png

Modified images

Path	Old	New

Report last updated at commit 23dad7b

[Copilot]

Pull request overview

Adds a new high-level Figure.paragraph method to typeset one or multiple paragraphs by wrapping GMT text module paragraph mode (-M), plus associated tests, baselines, and documentation wiring.

Changes:

• Implement pygmt.Figure.paragraph (new pygmt/src/paragraph.py) using a virtualfile multi-segment input and text -M.
• Add mpl image comparison tests and baseline artifacts for single- and multi-paragraph inputs.
• Expose the new method in the Figure API and documentation index, and cross-link from text docs.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
pygmt/src/paragraph.py	New Figure.paragraph implementation (builds text -M input via StringIO + virtual file).
pygmt/src/__init__.py	Exports paragraph so it can be attached to Figure.
pygmt/figure.py	Adds paragraph to the methods imported onto Figure.
pygmt/src/text.py	Adds a doc cross-reference from text to Figure.paragraph.
doc/api/index.rst	Adds Figure.paragraph to the API listing.
pygmt/tests/test_paragraph.py	Adds image tests covering single paragraph and two multi-paragraph input styles.
pygmt/tests/baseline/*.png.dvc	Adds DVC pointers for new image baselines.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[yvonnefroehlich]

As this is probaly the first implemention of this new method, clearance (and other parameters) will be add in a later PR, or?

[seisman]

As this is probaly the first implemention of this new method, clearance (and other parameters) will be add in a later PR, or?

Yes, this PR focuses on the required and frequently used parameters only.

[yvonnefroehlich]

Looks good to me!

On side questions: Using text in line 1 \n text in line 2 to get a new line is still not supported. As far as I understand it, two paragraphs are automatically seperated by a blank line via \n\n.

[yvonnefroehlich]

In case of multiple paragraphs, the entier text is surrounded by a box, or does each paragraph gets its own box?

[seisman]

the entier text is surrounded by a box

This is the answer.

[seisman]

On side questions: Using text in line 1 \n text in line 2 to get a new line is still not supported.

Do you mean in Figure.text? Yes, it's not supported, and it's also difficult to support in GMT.

As far as I understand it, two paragraphs are automatically seperated by a blank line via \n\n.

Yes.