GenericMappingTools / GenericMappingTools/pygmt
Expand pygmt subplot's documentation for the figsize and subsize parameters
- Dominant language
- Python
- Stars
- 874
- Forks
- 255
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 40
Description
**Description of the desired feature**
The docstring for [pygmt.subplot](https://www.pygmt.org/v0.4.0/api/generated/pygmt.Figure.subplot.html)'s `figsize` (-Ff) and `subsize` (-Fs) parameters are rather brief, and we should expand it to be longer following upstream GMT at https://docs.generic-mapping-tools.org/6.2/subplot.html#required-arguments-begin-mode. This is a follow up to #822.
## Current state :memo:
https://github.com/GenericMappingTools/pygmt/blob/d90b3fc889b53633deab6b4ab77612ac7a247c1b/pygmt/src/subplot.py#L56-L61
## Desired state :sparkles:
> figsize : tuple
> Specify the final figure dimensions as (*width*, *height*). The subplot
> dimensions are then calculated from the figure dimensions after
> accounting for the space that optional tick marks, annotations, labels,
> and margins occupy between subplots. As for other figures, annotations,
> ticks, and labels along the outside perimeter are not counted as part
> of the figure dimensions. To specify different subplot dimensions for
> each row (or column), append **+f** followed by a comma-separated list
> of width fractions, a slash, and then the list of height fractions. For
> example ``figsize="10c/10c+f3,1/1,2"`` will make the first column three
> times as wide as the second, while the second row will be twice as tall
> as the first row. A single number means constant widths (or heights)
> [Default].
>
> subsize : tuple
> Specify the dimensions of each subplot directly as (*width*, *height*).
> Then, the figure dimensions are computed from the subplot dimensions
> after adding the space that optional tick marks, annotations, labels,
> and margins occupy between subplots. As for other figures, annotations,
> ticks, and labels along the outside perimeter are not counted as part
> of the figure dimensions. To specify different subplot dimensions for
> each row (or column), append a comma-separated list of widths, a slash,
> and then the comma-separated list of heights. A single number means
> constant widths (or heights) [Default]. For example
> ``subsize="5c,8c/8c"`` will make the first column 5 cm wide and the
> second column 8 cm wide, with all having a constant height of 8 cm. The
> number of values must either be one (constant across the rows or
> columns) or exactly match the number of rows (or columns). For
> geographic maps, the height of each subplot depends on your map region
> and projection. There are two options:
>
> 1. Specify both ``region`` and ``projection`` and we use these to
> compute the height of each subplot. All subplots must share the same
> region and projection and you specify a zero *height*, or
> 2. Select *height* based on trial and error to suit your plot layout.
>
> Optionally, you may draw the outline (**+p**\ *pen*) or paint
> (**+g**\ *fill*\) the figure rectangle behind the subplots, add
> dividing lines between panels (**+w**\ *pen*), and even expand it via
> **+c**. These are most useful if you supply **frame="+n"** to
> ``subplot``, meaning no ticks or annotations will take place in the
> subplots. By default (**+af**), we auto-scale the fonts and pens based
> on the geometric mean dimension of the entire figure. Append **+as** to
> instead determine the scaling from the geometric mean subplot
> dimension.
## How to make the change :monocle_face:
1. First, read up our contributing guidelines at https://www.pygmt.org/v0.4.0/contributing.html#editing-the-documentation
2. Leave a comment below, stating that you will tackle this issue. We will assign you to this issue and you can then start working on it.
3. To edit the `subplot` module's docstring, go to https://github.com/GenericMappingTools/pygmt/edit/master/pygmt/src/subplot.py and add in the new docstring!
4. Submit a pull request, and be sure to fill it up with as much detail as possible.
:partying_face: Good luck, and let us know if you need any help :)
**Are you willing to help implement and maintain this feature?** Happy to review someone's Pull Request on it.
Contributor guide
Assessment
This issue has not been assessed yet.