# How to Contribute Documentation to GeoLibre: A Complete Guide for Contributors

> Learn how to contribute documentation to GeoLibre with our complete guide. Set up your environment and submit changes via pull request to the opengeos/GeoLibre repository.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-16

---

**To contribute documentation to GeoLibre, you need to follow the project's contribution guidelines, set up the documentation build environment, and submit changes via pull request to the `opengeos/GeoLibre` repository.**

GeoLibre is an open-source geospatial library maintained by the Open Geospatial Community (`opengeos`). Contributing documentation helps lower the barrier to entry for new users and ensures the project's features are properly explained. This guide walks through the exact steps based on the repository's source structure and contribution workflow.

---

## Prerequisites for Documentation Contributors

Before contributing, ensure you have the following tools installed and configured.

### Required Tools

- **Python 3.9+** — The documentation build system requires a modern Python version
- **Git** — For cloning and version control
- **GitHub account** — To fork the repository and open pull requests

---

## Setting Up the Documentation Environment

GeoLibre uses a standard Python documentation toolchain. Follow these steps to build docs locally.

### Clone the Repository

```bash
git clone https://github.com/opengeos/GeoLibre.git
cd GeoLibre

```

### Install Documentation Dependencies

The documentation dependencies are typically defined in `requirements` or [`pyproject.toml`](https://github.com/opengeos/GeoLibre/blob/main/pyproject.toml):

```bash
pip install -e ".[docs]"

```

Or if a separate docs requirements file exists:

```bash
pip install -r docs/requirements.txt

```

### Build Documentation Locally

Most GeoLibre documentation is built with **MkDocs** or **Sphinx**. Run the local server:

```bash

# For MkDocs

mkdocs serve

# For Sphinx

cd docs
make html
python -m http.server 8000 --directory _build/html

```

Verify your changes render correctly before submitting.

---

## Documentation File Structure

Understanding the repository layout helps you place contributions in the correct location.

### Key Documentation Paths

| Path | Purpose |
|------|---------|
| `docs/` | Main documentation source files |
| [`docs/index.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/index.md) | Project homepage and introduction |
| `docs/api/` | Auto-generated API reference documentation |
| `docs/examples/` | Tutorials and example notebooks |
| [`docs/contributing.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md) | Contributor guidelines (this guide extends it) |
| [`README.md`](https://github.com/opengeos/GeoLibre/blob/main/README.md) | Repository overview with quickstart |

Place new documentation in the appropriate subdirectory based on content type.

---

## Types of Documentation Contributions

GeoLibre welcomes several documentation improvement types.

### 1. Fix Typos and Clarity Issues

Minor corrections can be submitted directly via GitHub's web interface:

- Navigate to the file in `opengeos/GeoLibre`
- Click the pencil icon to edit
- Commit to a new branch and open a pull request

### 2. Add API Documentation

For new or undocumented functions, add **docstrings** following the NumPy style:

```python
def buffer_geometry(geometry, distance, resolution=16):
    """
    Create a buffer around a geometry.

    Parameters
    ----------
    geometry : shapely.geometry.base.BaseGeometry
        The input geometry to buffer.
    distance : float
        The buffer distance in the geometry's coordinate units.
    resolution : int, default 16
        The number of segments used to approximate a quarter circle.

    Returns
    -------
    shapely.geometry.base.BaseGeometry
        The buffered geometry.

    Examples
    --------
    >>> from shapely import Point
    >>> from geolibre import buffer_geometry
    >>> pt = Point(0, 0)
    >>> buffered = buffer_geometry(pt, distance=10)
    """
    pass

```

The documentation build system auto-generates API pages from these docstrings.

### 3. Write Tutorials and Examples

Add Jupyter notebooks to `docs/examples/`:

```bash
cp your_notebook.ipynb docs/examples/

```

Then reference them in the appropriate [`mkdocs.yml`](https://github.com/opengeos/GeoLibre/blob/main/mkdocs.yml) or `toctree` configuration.

---

## Contribution Workflow

Follow this process to ensure your documentation contribution is accepted.

### Step 1: Fork and Branch

```bash
git checkout -b docs/your-description

# Example: docs/fix-buffer-typo or docs/add-raster-tutorial

```

### Step 2: Make Changes

Edit files in `docs/` or add docstrings to source files. For substantial rewrites, open an issue first to discuss scope.

### Step 3: Build and Test Locally

```bash

# Verify no build errors

mkdocs build --strict

# Check for broken links

mkdocs build 2>&1 | grep -i "warning\|error"

```

### Step 4: Commit with Clear Messages

```bash
git commit -m "docs: clarify buffer_geometry resolution parameter

- Adds parameter description for resolution
- Includes example with non-default value
- Fixes #123"

```

Use the `docs:` prefix for documentation commits.

### Step 5: Push and Open Pull Request

```bash
git push origin docs/your-description

```

In your PR description, include:
- What changed and why
- Screenshots (for visual changes)
- Link to rendered preview if available

---

## Review Criteria for Documentation PRs

Maintainers evaluate documentation contributions against these standards:

- **Accuracy** — Technical content must match the actual API implementation
- **Completeness** — New features include docstrings, examples, and narrative docs
- **Style consistency** — Follows existing heading structure and tone
- **Build success** — `mkdocs build` or `make html` completes without errors
- **Accessibility** — Clear language, alt text for images, keyboard-navigable examples

---

## Summary

- **Fork** the `opengeos/GeoLibre` repository and create a descriptive branch
- **Set up** the local build environment with `pip install -e ".[docs]"`
- **Edit** files in `docs/` or add NumPy-style docstrings to source code
- **Build** locally with `mkdocs serve` or `make html` to verify changes
- **Submit** a pull request with clear commit messages and description

Documentation contributions follow the same review process as code changes and are essential to GeoLibre's usability.

---

## Frequently Asked Questions

### How do I find documentation that needs improvement?

Check the **GitHub Issues** tab for issues labeled `good first issue` or `documentation`. You can also search `docs/` for `TODO` comments or sections marked as incomplete. The API reference may list functions without descriptions.

### Can I contribute documentation without installing Python locally?

Yes, for minor edits. GitHub's web interface allows direct file editing, which creates a fork and branch automatically. For structural changes or new tutorials, local builds are strongly recommended to verify formatting and links.

### What documentation style guide does GeoLibre follow?

GeoLibre follows **NumPy docstring conventions** for API documentation and **Markdown** for narrative documentation. Use complete sentences, active voice, and include runnable code examples where possible. Match the existing heading hierarchy (H2 for sections, H3 for subsections).

### How long does documentation review typically take?

Simple typo fixes are often merged within 24–48 hours. Substantial documentation additions may take 1–2 weeks depending on maintainer availability and required revisions. Respond promptly to reviewer feedback to expedite the process.