GenericMappingTools / GenericMappingTools/pygmt
Add documentation for common options/parameter in the "Technical Reference" section
- 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

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
Assessment
This issue has not been assessed yet.