Documentation enhancements pre release (#1175)

* Update the Python support version

* Add main missing docs strings

* Update citation count

* Add pre-commit dev doc

* Update version to reflect prerelease candidate

* ci: update publish workflow to Python 3.11 and modern action versions

Author: henrykironde

.bumpversion.toml

@@ -1,19 +1,18 @@
 [tool.bumpversion]
-current_version = "1.5.3-dev0"
+current_version = "2.0.0rc1"
 
 parse = """(?x)
     (?P<major>0|[1-9]\\d*)\\.
     (?P<minor>0|[1-9]\\d*)\\.
     (?P<patch>0|[1-9]\\d*)
     (?:
-        -                             # dash separator for pre-release section
-        (?P<pre_l>[a-zA-Z-]+)         # pre-release label
+        (?P<pre_l>[a-zA-Z]+)          # pre-release label (no dash)
         (?P<pre_n>0|[1-9]\\d*)        # pre-release version number
     )?                                # pre-release section is optional
 """
 serialize = [
     "{major}.{minor}.{patch}",
-    "{major}.{minor}.{patch}-{pre_l}{pre_n}"
+    "{major}.{minor}.{patch}{pre_l}{pre_n}"
 ]
 
 [tool.bumpversion.parts.pre_l]

.github/workflows/publish.yml

@@ -11,18 +11,18 @@ jobs:
     runs-on: ubuntu-latest
     if: "!contains(github.ref, '-dev')"
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.11"
 
       - name: Build package
         run: |
           python -m pip install --upgrade pip build
           python -m build
 
       - name: Publish to Test PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@release/v2
         with:
           password: ${{ secrets.TEST_PYPI_TOKEN }}
           repository-url: https://test.pypi.org/legacy/
@@ -34,18 +34,18 @@ jobs:
     if: "!contains(github.ref, '-dev')"  # Skip dev versions
     needs: [test-pypi]  # Wait for test-pypi to succeed
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.9"
+          python-version: "3.11"
 
       - name: Build package
         run: |
           python -m pip install --upgrade pip build
           python -m build
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@release/v2
         with:
           password: ${{ secrets.PYPI_TOKEN }}
           skip-existing: true

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Developer's Guide
 
-Depends on Python 3.9+
+Depends on Python 3.10+
 
 ## Getting started
 
@@ -28,12 +28,12 @@ Depends on Python 3.9+
 
 4. Check or confirm your settings using `git remote -v`
 
-   ```text
+```bash
    origin git@github.com:[your user name]/DeepForest.git (fetch)
    origin git@github.com:[your user name]/DeepForest.git (push)
    upstream https://github.com/weecology/DeepForest.git (fetch)
    upstream https://github.com/weecology/DeepForest.git (push)
-   ```
+```
 
 5. Install the package from the main directory.
 
@@ -70,26 +70,85 @@ $ pip install . --upgrade  # or python setup.py install
 $ pytest -v
 ```
 
-### Checking and fixing code style
+### Code Quality and Style
+
+We use [pre-commit](https://pre-commit.com/) to ensure consistent code quality and style across the project. Pre-commit runs automated checks and fixes before each commit to catch issues early.
+
+#### Setting up pre-commit
+
+1. **Install pre-commit** (if not already installed):
+   ```bash
+   pip install pre-commit
+   ```
+
+2. **Install the pre-commit hooks** in your local repository:
+   ```bash
+   pre-commit install
+   ```
+
+3. **Run pre-commit on all files** (optional, for initial setup):
+   ```bash
+   pre-commit run --all-files
+   ```
+
+#### What pre-commit does
+
+Our pre-commit configuration (`.pre-commit-config.yaml`) includes:
+
+- **Code formatting**: Uses [Ruff](https://docs.astral.sh/ruff/) for fast Python linting and formatting
+- **Import sorting**: Automatically sorts and organizes imports
+- **Docstring formatting**: Uses [docformatter](https://github.com/PyCQA/docformatter) to format docstrings
+- **Notebook formatting**: Formats Jupyter notebooks in the documentation
+- **File checks**: Ensures files end with newlines, removes trailing whitespace, checks YAML/JSON syntax
+- **Large file detection**: Prevents accidentally committing large files
+
+#### Running pre-commit manually
+
+You can run pre-commit checks manually at any time:
+
+```bash
+# Run on staged files only
+pre-commit run
+
+# Run on all files
+pre-commit run --all-files
+
+# Run a specific hook
+pre-commit run ruff
+```
+
+#### Fixing pre-commit issues
 
-#### Using Yapf
+Most pre-commit hooks will automatically fix issues for you. If a hook fails:
 
-We use [yapf](https://github.com/google/yapf) for code formatting and style checking.
+1. **Check the output** - pre-commit will show you what needs to be fixed
+2. **Re-run the hook** - many hooks can auto-fix issues:
+   ```bash
+   pre-commit run --all-files
+   ```
+3. **Stage the fixed files** and commit again:
+   ```bash
+   git add .
+   git commit -m "Your commit message"
+   ```
 
-The easiest way to make sure your code is formatted correctly is to integrate it into your editor.
-See [EDITOR SUPPORT](https://github.com/google/yapf/blob/main/EDITOR%20SUPPORT.md).
+#### Bypassing pre-commit (not recommended)
 
-You can also run yapf from the command line to cleanup the style in your changes:
+If you need to bypass pre-commit for a specific commit (not recommended for regular development):
 
 ```bash
-yapf -i --recursive src/deepforest/ --style=.style.yapf
+git commit --no-verify -m "Your commit message"
 ```
 
-If the style tests fail on a pull request, running the above command is the easiest way to fix this.
+#### Editor integration
+
+For the best development experience, consider integrating these tools directly into your editor:
 
-#### Using pre-commit
+- **VS Code**: Install the Ruff extension for real-time linting and formatting
+- **PyCharm**: Configure Ruff as an external tool
+- **Vim/Neovim**: Use plugins like `nvim-lspconfig` with the Ruff language server
 
-We configure all our checks using the `.pre-commit-config.yaml` file. To verify your code styling before committing, you should run `pre-commit install` to set up the hooks, followed by `pre-commit run` to execute them. This will apply the formatting rules specified in the `.style.yapf` file. For additional information, please refer to the [pre-commit documentation](https://pre-commit.com/index.html).
+For more information, see the [pre-commit documentation](https://pre-commit.com/).
 
 ## Documentation
 
@@ -175,14 +234,15 @@ The model will be uploaded to [https://huggingface.co/weecology/[model-name]](ht
 
 ### CropModel
 
-```python```
+```python
 from deepforest.model import CropModel
 
 crop_model = CropModel()
 crop_model.push_to_hub("weecology/cropmodel-deadtrees")
 
 # Reload it later
 crop_model.from_pretrained("Weecology/cropmodel-deadtrees")
+
 ```
 
 Please name the cropmodel based on what is being classified.

HISTORY.md

@@ -1,8 +1,9 @@
 # DeepForest Changelog
 
-## Version 2.0.0 (Date: TBD)
+## Version 2.0.0rc1 (Date: October 21, 2025)
 
-### Breaking Changes - Deprecated Items Removed:
+### Release Candidate 1 - Beta Release
+#### Breaking Changes - Deprecated Items Removed:
 
 **Removed Functions:**
 - `xml_to_annotations()` - Use `utilities.read_pascal_voc(path)` or the general `utilities.read_file(path)`.

README.md

@@ -7,7 +7,7 @@
 [![Version](https://img.shields.io/pypi/v/DeepForest.svg)](https://pypi.python.org/pypi/DeepForest)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/deepforest)](https://pypi.python.org/pypi/DeepForest)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2538143.svg)](https://doi.org/10.5281/zenodo.2538143)
-[![Python Version](https://img.shields.io/badge/python-%3E%3D3.8%2C%20%3C3.13-blue.svg)](https://www.python.org/downloads/)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10%2C%20%3C3.13-blue.svg)](https://www.python.org/downloads/)
 [![Citations](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/weecology/DeepForest/refs/heads/main/citation_count.json)](https://scholar.google.com/scholar?hl=en&as_sdt=40005&sciodt=0,10&cites=4018186955550406830&scipsc=&q=)
 
 ![](www/MEE_Figure4.png)

citation_count.json

@@ -1,6 +1,6 @@
 {
     "schemaVersion": 1,
     "label": "Citations",
-    "message": "118",
+    "message": "123",
     "color": "blue"
 }

docs/getting_started/install.md

@@ -36,9 +36,29 @@ pip install .
 ```bash
 git clone https://github.com/weecology/DeepForest.git
 cd DeepForest
-uv sync --all-extras -dev
+uv sync --all-extras --dev
 ```
 
+## Development Installation
+
+For developers who want to contribute to DeepForest, install the package in development mode with all dependencies:
+
+```bash
+git clone https://github.com/weecology/DeepForest.git
+cd DeepForest
+pip install .'[dev,docs]'
+```
+
+Or using uv:
+
+```bash
+git clone https://github.com/weecology/DeepForest.git
+cd DeepForest
+uv sync --all-extras --dev
+```
+
+This installs DeepForest in editable mode with development and documentation dependencies.
+
 ## GPU support
 
 PyTorch can be run on GPUs to allow faster model training and prediction. DeepForest is a PyTorch Lightning module, which automatically distributes data to available GPUs. If using a release model with training, the module can be moved from CPU to GPU for prediction using the `pytorch.to()` method.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepforest"
-version = "1.5.3-dev0"
+version = "2.0.0rc1"
 description = "Platform for individual detection from airborne remote sensing including trees, birds, and livestock. Supports multiple detection models, adding models for species classification, and easy fine tuning to particular ecosystems."
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

src/deepforest/_version.py

@@ -1,2 +1,2 @@
-__version__ = "1.5.3-dev0"
+__version__ = "2.0.0rc1"
 # Version updated using bump-my-version

src/deepforest/model.py

@@ -28,11 +28,11 @@ class BaseModel:
         config: DeepForest configuration object
     """
 
-    def __init__(self, config):
+    def __init__(self, config) -> None:
         # Check for required properties and formats
         self.config = config
 
-    def create_model(self):
+    def create_model(self) -> torch.nn.Module:
         """Create model from configuration.
 
         Must be implemented by subclasses to return a PyTorch nn.Module.
@@ -43,7 +43,7 @@ def create_model(self):
             "Take in args and return a pytorch nn module."
         )
 
-    def check_model(self):
+    def check_model(self) -> None:
         """Validate model follows DeepForest guidelines.
 
         Tests model with dummy data to ensure proper input/output
@@ -66,7 +66,15 @@ def check_model(self):
         assert model_keys == ["boxes", "labels", "scores"]
 
 
-def simple_resnet_50(num_classes=2):
+def simple_resnet_50(num_classes: int = 2) -> torch.nn.Module:
+    """Create a simple ResNet-50 model for classification.
+
+    Args:
+        num_classes: Number of output classes for the final layer
+
+    Returns:
+        torch.nn.Module: ResNet-50 model with modified final layer
+    """
     m = models.resnet50(weights=models.ResNet50_Weights.DEFAULT)
     num_ftrs = m.fc.in_features
     m.fc = torch.nn.Linear(num_ftrs, num_classes)