WIP: DOC: Add a gallery example to show formating long text as paragraphs

[yvonnefroehlich]

Description of proposed changes

This PR aims to add a gallery example to show the usage of the newly added high-level method Figure.paragraph.

Currently this is a standalone example. I am a bit wondering if it can make sense to add this to the already existing gallery example Formatting text becauseFigure.paragraph is related to -M of Figure.text.

Please note the upstream bug reported in #4590. I will write a related GMT code example and issue hopefully this night or tomorrow - Edit Upstream bug report at GenericMappingTools/gmt#8989 - Edit 2026/04/22 PR with a fix in the GMT codes was merged.

See PR #4605.

Preview: https://pygmt-dev--4592.org.readthedocs.build/en/4592/gallery/embellishments/paragraph.html

Guidelines

• General Guidelines for Pull Request
• Guidelines for Contributing Documentation
• Guidelines for Contributing Code

Slash Commands

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

• /format: automatically format and lint the code

[seisman]

I am a bit wondering if it can make sense to add this to the already existing gallery example Formatting text

I think it makes more sense to have a separate example.

becauseFigure.paragraph is related to -M of Figure.text.

I feel these are technical details that users don't have to know, especially for PyGMT users who are not familiar with GMT CLI syntax.

[seisman]

Maybe we can try to recreate the GMT example/test at https://github.com/GenericMappingTools/gmt/blob/master/test/pstext/shade_text.sh.

[yvonnefroehlich]

Maybe we can try to recreate the GMT example/test at https://github.com/GenericMappingTools/gmt/blob/master/test/pstext/shade_text.sh.

Looks like a nice example, but I think it would be good to use a text that consists of at least two paragraphs.
In case you already worked locally on a gallery example based on this example, we can also close this PR, as my example is at an early state and you can open an own PR for a gallery example based on the GMT example.

[yvonnefroehlich]

Before continuing with this example in PyGMT we need to introduce the parameters for -S and -C.

[seisman]

I think we don't have to reproduce the example exactly, so -S and -C are not needed.

[yvonnefroehlich]

Agree, we can still extend the gallery example later to include this parameters if we feel this makes sense.