### Example: Linking to Install Instructions

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

This example shows how to use the :doc: directive to link to a specific documentation file, such as the installation instructions.

```rst
:doc:`Install instructions </install>`
```

--------------------------------

### Add Example Code to Docstring

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

Contribute an example by adding an 'Example' header and the code below it within a function's docstring. Ensure all lines start with '>>>'.

```python
Example
-------
>>> import pygmt
>>> # Comment describing what is happening
>>> Code example
```

--------------------------------

### Install PyGMT with Mamba

Source: https://github.com/genericmappingtools/pygmt/blob/main/README.md

Use this command for a simple installation of PyGMT if you are using mamba.

```bash
mamba install --channel conda-forge pygmt
```

--------------------------------

### Example: Linking to GMT COLOR_FOREGROUND Parameter

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

This example shows how to link to a GMT configuration parameter using the :gmt-term: directive.

```rst
:gmt-term:`COLOR_FOREGROUND`
```

--------------------------------

### Install PyGMT with Optional Dependencies

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Installs PyGMT along with all of its optional dependencies using pip.

```bash
python -m pip install pygmt[all]
```

--------------------------------

### Install PyGMT with Conda

Source: https://github.com/genericmappingtools/pygmt/blob/main/README.md

Use this command for a simple installation of PyGMT if you are using conda.

```bash
conda install --channel conda-forge pygmt
```

--------------------------------

### Example: Linking to GMT makecpt.html

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

This example demonstrates linking to a specific HTML page within the GMT documentation using the :gmt-docs: directive.

```rst
:gmt-docs:`makecpt.html`
```

--------------------------------

### Install PyGMT with Pip

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Installs the latest stable release of PyGMT from PyPI using pip.

```bash
python -m pip install pygmt
```

--------------------------------

### Example: Linking to pygmt.Figure.grdview

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

This example demonstrates how to use the :meth: directive to link to a specific method within the PyGMT API documentation.

```rst
:meth:`pygmt.Figure.grdview`
```

--------------------------------

### Install PyGMT Development Version with Pip

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Installs the latest development version of PyGMT from TestPyPI using pip.

```bash
python -m pip install --pre --extra-index-url https://test.pypi.org/simple/ pygmt
```

--------------------------------

### Check PyGMT Installation and Versions

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Run this Python code after activating your PyGMT environment to verify the installation and display version information for PyGMT and its dependencies.

```python
import pygmt
pygmt.show_versions()
```

--------------------------------

### Install Optional Dependencies (mamba)

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Install optional dependencies like contextily, geopandas, ipython, and rioxarray into the active 'pygmt' environment using mamba to enable more PyGMT functionalities.

```bash
mamba install contextily geopandas ipython pyarrow-core rioxarray
```

--------------------------------

### Create Virtual Environment with Dependencies (mamba)

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Create a new virtual environment named 'pygmt' using mamba, installing Python and core dependencies including GMT.

```bash
mamba create --name pygmt python=3.14 numpy pandas xarray packaging gmt
```

--------------------------------

### Install PyGMT Source Code (Editable Mode)

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

Install the current source code into your active testing environment in editable mode. Changes made to the source code will be immediately reflected when importing the package.

```bash
make install  # on Linux/macOS
```

```bash
python -m pip install --no-deps -e .  # on Windows
```

--------------------------------

### Install PyGMT with Mamba

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Use this command to install the latest stable release of PyGMT from conda-forge using mamba.

```bash
mamba install pygmt
```

--------------------------------

### Install PyGMT Jupyter Kernel

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Install a PyGMT kernel for Jupyter notebooks to resolve ModuleNotFoundError. This involves installing the virtual environment properly and listing available kernels.

```python
python -m ipykernel install --user --name pygmt  # install virtual environment properly
jupyter kernelspec list --json
```

--------------------------------

### Create Virtual Environment with Dependencies (conda)

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Create a new virtual environment named 'pygmt' using conda, installing Python and core dependencies including GMT.

```bash
conda create --name pygmt python=3.14 numpy pandas xarray packaging gmt
```

--------------------------------

### Install Optional Dependencies (conda)

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Install optional dependencies like contextily, geopandas, ipython, and rioxarray into the active 'pygmt' environment using conda to enable more PyGMT functionalities.

```bash
conda install contextily geopandas ipython pyarrow-core rioxarray
```

--------------------------------

### Configuring DVC Remote Authentication

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

Set up basic authentication for the DVC remote. This is a one-time setup for contributing test images.

```bash
dvc remote modify upstream --local auth basic
dvc remote modify upstream --local user "$DAGSHUB_USER"
dvc remote modify upstream --local password "$DAGSHUB_PASS"
```

--------------------------------

### Activate PyGMT Environment with Conda

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Activate the 'pygmt' conda environment created with conda to start using PyGMT.

```bash
conda activate pygmt
```

--------------------------------

### Create a Basic World Map with PyGMT

Source: https://github.com/genericmappingtools/pygmt/blob/main/README.md

This Python code snippet demonstrates how to create a simple world map with colored land and water, and adds text to the map. It requires the pygmt library to be installed.

```python
import pygmt

fig = pygmt.Figure()
fig.basemap(projection="R7c", region=[0, 360, -90, 90], frame=True)
fig.coast(land="tan", water="lightblue")
fig.text(position="MC", text="PyGMT", font="40p,AvantGarde-Book,red@75")
fig.show()
```

--------------------------------

### Activate PyGMT Environment with Mamba

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Activate the 'pygmt' conda environment created with mamba to start using PyGMT.

```bash
mamba activate pygmt
```

--------------------------------

### Menu Block

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/_templates/layout.html

This Jinja2 block extends the base menu and adds a 'Getting help and contributing' section with a list of links if 'menu_links' are defined.

```html
{% block menu %} {{ super() }} {% if menu_links %} Getting help and contributing {% for text, link in menu_links %}*   [{{ text }}]({{ link }}) {% endfor %} {% endif %} {% endblock %}
```

--------------------------------

### Create PyGMT Environment with Conda

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Use this command to create a new conda environment named 'pygmt' with PyGMT installed from the conda-forge channel using conda.

```bash
conda create --name pygmt --channel conda-forge pygmt
```

--------------------------------

### Create Conda Environment from environment.yml

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

Use this command to create a new conda environment based on the project's `environment.yml` file. This ensures all necessary development dependencies are installed.

```bash
mamba env create --file environment.yml
```

--------------------------------

### Build HTML Documentation Locally

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

Navigate to the doc directory and run 'make all' to build the HTML documentation files locally. These files will be generated in 'doc/_build/html'.

```bash
cd doc
make all
```

--------------------------------

### Run All Tests and Pull Data

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

Execute the full test suite and download necessary data files from the DVC cache.

```bash
dvc status
dvc pull
make test
```

--------------------------------

### Full DVC and Git Workflow for Test Images

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

This workflow covers pulling changes, generating new baseline images, staging them with DVC, and pushing updates to both Git and DVC remotes.

```bash
# Sync with both git and dvc remotes
git pull
dvc pull

# Generate new baseline images
pytest --mpl-generate-path=baseline pygmt/tests/test_logo.py
mv baseline/*.png pygmt/tests/baseline/

# Generate hash for baseline image and stage the *.dvc file in git
dvc status  # Check which files need to be added to dvc
dvc add pygmt/tests/baseline/test_logo.png
git add pygmt/tests/baseline/test_logo.png.dvc

# Commit changes and push to both the git and dvc remotes
git commit -m "Add test_logo.png into DVC"
dvc status --remote upstream  # Report which files will be pushed to the dvc remote
dvc push  # Run before git push to enable automated testing with the new images
git push
```

--------------------------------

### Check Code Quality with Ruff

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

Execute this command to run Ruff in check mode and identify potential code quality issues.

```bash
make check   # Runs Ruff in check mode
```

--------------------------------

### Create PyGMT Environment with Mamba

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/install.md

Use this command to create a new conda environment named 'pygmt' with PyGMT installed from the conda-forge channel using mamba.

```bash
mamba create --name pygmt --channel conda-forge pygmt
```

--------------------------------

### Format Code with Ruff

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

Run this command to automatically format your code according to PyGMT's style guidelines using Ruff.

```bash
make format
```

--------------------------------

### Configuring Display Settings

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/api/index.rst

Function to configure display settings for PyGMT.

```APIDOC
## pygmt.set_display

### Description
Configures the display settings for PyGMT.

### Method
`pygmt.set_display`
```

--------------------------------

### Skip Doctest for a Function

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

To prevent a specific function's example code from being run during testing, add this line to the top of the module. Replace 'function_name' with the actual function name.

```python
__doctest_skip__ = ["function_name"]
```

--------------------------------

### Input/Output

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/api/index.rst

Function for loading data.

```APIDOC
## pygmt.load_dataarray

### Description
Loads data into an xarray DataArray.

### Method
`pygmt.load_dataarray`
```

--------------------------------

### Justification Codes for Plot Embellishments (Colorbar)

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/techref/justification_codes.md

Shows the application of justification codes for plot embellishments, using a colorbar as an example. This helps in aligning and positioning elements relative to the map or figure boundaries.

```python
"""
Script showing justification codes for plot embellishments, e.g., a colorbar.
"""
fig = pygmt.Figure()
fig.basemap(projection="X10c/2c", region=[-size, size, -size, size], frame=0)

fig.colorbar(
    cmap="SCM/buda",
    frame=0,
    position="MC",
    length=10,
    width=2,
    orientation="horizontal",
)

for code in codes:
    fig.text(
        font="10p,1,black",
        position=code,
        justify=code,
        text=code,
        offset="j0.3c/0.15c+v1p,gray30",
    )
fig.plot(x=x1, y=y1, style="c0.2c", fill="steelblue", no_clip=True)

fig.show(width=600)

```

--------------------------------

### Run Tests Matching Keyword

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

Execute tests whose names match a specific keyword expression.

```bash
pytest -k KEYWORD pygmt/tests
```

--------------------------------

### Visualize Justification Codes in PyGMT

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/techref/justification_codes.md

Demonstrates the nine possible justification codes (TL, TC, TR, ML, MC, MR, BL, BC, BR) by placing text labels at corresponding positions on a figure. Useful for understanding spatial referencing in PyGMT.

```python
"""
Script showing the justification codes used in GMT / PyGMT.
"""
import pygmt

size = 5
x1 = [-size, 0, size, size, size, 0, -size, -size, 0]
y1 = [-size, -size, -size, 0, size, size, size, 0, 0]
codes = ["BL", "BC", "BR", "MR", "TR", "TC", "TL", "ML", "MC"]

fig = pygmt.Figure()
fig.basemap(projection="X10c/6c", region=[-size, size, -size, size], frame=0)

fig.text(
    font="15p,1,black",
    x=x1,
    y=y1,
    text=codes,
    justify=codes,
    offset="j0.5c/0.5c+v2p,gray30",
)

fig.plot(x=x1, y=y1, style="c0.3c", fill="steelblue", no_clip=True)

fig.text(
    font="15p",
    offset="j0.5c/0.5c",
    no_clip=True,
    x=[size, size, size, -size, 0, size],
    y=[size, 0, -size, size, size, size],
    justify=["ML", "ML", "ML", "BC", "BC", "BC"],
    text=[
        "@%1%T@%%op",
        "@%1%M@%%iddle",
        "@%1%B@%%ottom",
        "@%1%L@%%eft",
        "@%1%C@%%enter",
        "@%1%R@%%ight",
    ],
)

fig.show(width=600)

```

--------------------------------

### Generate Visual Font Samples with PyGMT

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/techref/fonts.md

This script uses PyGMT to create a visual representation of all supported fonts, displaying their names and corresponding font numbers. It's useful for previewing how each font will appear in plots.

```python
import pygmt

x1, x2, dx = 0, 7, 0.75

fig = pygmt.Figure()
# Draw the table
fig.basemap(region=[-0.5, 14, -1.5, 18], projection="X14c/-10c", frame=0)
fig.plot(x=[-0.5, 14], y=[-0.5, -0.5])
for x in (0.5, 6.5, 7.5):
    fig.plot(x=[x, x], y=[-1.5, 18])
# Table header
fig.text(
    x=[x1, x1 + dx, x2, x2 + dx],
    y=[-1] * 4,
    text=["#", "Font Name"] * 2,
    justify=["MC", "ML"] * 2,
    font="Helvetica-Bold",
)
# Fonts
for i, font in enumerate(fonts):
    x0 = x1 if i < 17 else x2
    y0 = i % 17
    font_no, font_name = i, font

    # Deal with special cases
    if font in ["Symbol", "ZapfDingbats"]:
        font_name = f"{font} @%0%({font})@%%"
    if font == "ZapfDingbats":
        font_no = "@%0%34@%%"
        y0 = 17

    fig.text(
        x=[x0, x0 + dx],
        y=[y0] * 2,
        text=[font_no, font_name],
        justify=["MC", "ML"],
        font=font,
    )
fig.show(width=600)
```

--------------------------------

### Enums

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/api/index.rst

Enumerations for PyGMT configurations.

```APIDOC
## pygmt.enums.GridRegistration

### Description
Enumeration for grid registration types.

### Enum
`pygmt.enums.GridRegistration`
```

```APIDOC
## pygmt.enums.GridType

### Description
Enumeration for grid types.

### Enum
`pygmt.enums.GridType`
```

--------------------------------

### Enable Verbose GMT Logging

Source: https://github.com/genericmappingtools/pygmt/blob/main/doc/contributing.md

Add this line after import statements to enable verbose GMT command logging for debugging upstream GMT issues.

```python
pygmt.config(GMT_VERBOSE="d")
```