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.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

---

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

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

---

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

[Copilot]

Figure.paragraph currently doesn’t accept **kwargs (nor merge them into AliasSystem), which prevents users from passing through other valid text options in paragraph mode (e.g., -G, -W, -N, -Q, -t, -c, -V). Consider adding a **kwargs parameter and calling aliasdict.merge(kwargs) so unsupported/advanced flags can still be used without waiting for first-class wrapper parameters (and without a future breaking API change).

Suggested change

	alignment: Literal["left", "center", "right", "justified"] = "left",
	alignment: Literal["left", "center", "right", "justified"] = "left",
	**kwargs,