GenericMappingTools / GenericMappingTools/pygmt

Add documentation for common options/parameter in the "Technical Reference" section

Open
#3,843 2 comments 1 reaction 0 assignees View on GitHub
documentation help wanted
Dominant language
Python
Stars
874
Forks
255
Avg merge
1d 21h
Merged PRs (30d)
40

Description

GMT modules have common options (e.g., -J/-R/-V), which are aliased to standardized parameters in PyGMT (e.g., projection, region, verbose). Currently, the docstrings for some parameters are lengthy and take up a significant portion of the documentation pages, making it harder to focus on module-specific options.

To improve readability, I propose moving the detailed explanations of these common parameters to a dedicated page in the "Technical Reference" section. In the wrapper documentation, their descriptions can be condensed, with a link to the full explanation.

For example, currently, the `verbose` has docstrings like below

![Image](https://github.com/user-attachments/assets/b60907bf-1d0b-42c1-9e6f-377fb0f89950)

and it can be simplified to:
```
verbose
Select verbosity level. [See detailed explanation.]
```

This approach reduces the documentation length of wrappers, and makes wrapper-specific parameters more prominent.

**TODO list**

Here is a complete list of GMT common options (https://docs.generic-mapping-tools.org/latest/std-opts.html).

- [ ] `-B`
- [ ] `-J`
- [ ] `-R`
- [x] ~~`-U`~~ Unused in PyGMT
- [x] `-V` #3844 @seisman
- [x] ~~`-X`~~: Unused in PyGMT
- [x] ~~`-Y`~~: Unused in PyGMT
- [ ] `-a`
- [ ] `-b`
- [x] `-c` #3930
- [ ] `-d`
- [ ] `-e`
- [ ] `-f`
- [ ] `-g`
- [ ] `-h`
- [ ] `-i`
- [x] `-j` #3868 @seisman
- [ ] `-l`
- [ ] `-n`
- [ ] `-o`
- [ ] `-p`
- [ ] `-q`
- [ ] `-r`
- [ ] `-s`
- [ ] `-t`
- [ ] `-w`
- [x] `-x` #3923
- [ ] ~~`-:`~~ Unused in PyGMT

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.