26

docs/README.md

@@ -6,7 +6,7 @@ This directory contains the Sphinx documentation for Φ-Down.
 
 1. Install documentation dependencies:
    ```bash
-   pip install -r requirements.txt
+   python3 -m pip install -r requirements.txt
    ```
 
 2. Build the documentation:
@@ -26,13 +26,14 @@ This directory contains the Sphinx documentation for Φ-Down.
   - `getting_started.rst` - Getting started guide
   - `installation.rst` - Installation instructions
   - `user_guide.rst` - Comprehensive user guide
+  - `ais_guide.rst` - AIS data download and filtering guide
+  - `burst_mode.rst` - Sentinel-1 burst search and download guide
   - `api_reference.rst` - API reference
   - `examples.rst` - Code examples
   - `contributing.rst` - Contributing guidelines
   - `changelog.rst` - Version history
   - `conf.py` - Sphinx configuration
   - `_static/` - Static files (CSS, images)
-  - `_templates/` - Custom templates
 
 - `build/` - Generated documentation (HTML)
 
@@ -46,7 +47,7 @@ The documentation uses the Read the Docs theme with custom styling for PhiLab br
 
 ## API Documentation
 
-API documentation is automatically generated using Sphinx AutoAPI from the Python source code docstrings. The configuration is in `conf.py`.
+API documentation is generated with Sphinx AutoAPI from the Python source tree configured in `source/conf.py`.
 
 ## Contributing to Documentation
 

docs/requirements.txt

@@ -1,7 +1,7 @@
 # Documentation requirements for Sphinx
-sphinx>=8.0.0
-sphinx-rtd-theme>=3.0.0
-sphinx-autodoc-typehints>=2.0.0
-myst-parser>=4.0.0
+sphinx>=7.0.0,<8.0.0
+sphinx-rtd-theme>=1.3.0,<4.0.0
+sphinx-autodoc-typehints>=1.24.0,<3.0.0
+myst-parser>=3.0.0,<4.0.0
 sphinx-copybutton>=0.5.0
-sphinx-autoapi>=3.0.0
+sphinx-autoapi>=2.5.0,<4.0.0

docs/source/burst_mode.rst

@@ -134,7 +134,7 @@ The simplest burst search uses only temporal filters:
 Example 2: Burst Search with Spatial Filter (AOI)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Combine burst mode with spatial filtering using a WKT polygon:
+Combine burst mode with spatial filtering using a supported WKT geometry such as a polygon:
 
 .. code-block:: python
 
@@ -389,7 +389,7 @@ Use AOI with swath/polarization filters to get bursts covering your study area:
 
     searcher.query_by_filter(
         burst_mode=True,
-        aoi_wkt=your_polygon_wkt,
+        aoi_wkt=your_aoi_wkt,
         swath_identifier='IW2',
         polarisation_channels='VV',
         start_date='2024-08-01T00:00:00',

docs/source/changelog.rst

@@ -3,9 +3,75 @@ Changelog
 
 This document tracks all notable changes to Φ-Down.
 
+.. note::
+
+   The package metadata currently reports version ``0.1.25``. The changelog
+   entries below have not yet been backfilled for every patch release after
+   ``0.1.22``.
+
 The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,
 and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 
+[Unreleased]
+------------
+
+*(None)*
+
+### Added
+- *(reserved for future release notes)*
+
+[0.1.26] - 2026-03-15
+---------------------
+
+### Added
+- ``query_by_filter(skip=...)`` for manual page offsets when fetching a single result page at a time
+- ``mode="fast"`` and ``mode="safe"`` for product downloads in the Python API and CLI
+- Native resumable product download support with persisted state tracking and dedicated tests
+- Enhanced retry behavior in safe mode with automatic exponential backoff and clear progress messages:
+
+  * 🔄 Attempt indicators showing current/total attempts
+  * ⚠️ Retry warnings with countdown timers before next attempt
+  * ✅ Success confirmation messages
+  * ❌ Failure summaries after exhausting all retries
+
+- Support for additional AOI WKT geometry types across search helpers and footprint visualization
+
+  .. code-block:: python
+
+     from phidown.search import CopernicusDataSearcher
+
+     filters = dict(
+         collection_name="SENTINEL-1",
+         product_type="GRD",
+         start_date="2024-01-01T00:00:00",
+         end_date="2024-01-31T23:59:59",
+         top=20,
+     )
+
+     searcher = CopernicusDataSearcher()
+     searcher.query_by_filter(**filters, skip=0)
+     page_1 = searcher.execute_query()
+
+     searcher.query_by_filter(**filters, skip=20)
+     page_2 = searcher.execute_query()
+
+     # Use `skip` when a frontend needs one page at a time.
+     # `count=True` still performs eager multi-page retrieval and cannot be combined with `skip`.
+
+### Changed
+ - Documented manual pagination examples in Sphinx guides
+- Clarified that ``count=True`` still performs eager multi-page retrieval and cannot be combined with ``skip``
+- ``fast`` mode now prefers the ``s5cmd`` transfer path, while ``safe`` mode uses native resumable downloads
+- CLI and user guides now document ``--mode`` as the primary download selector and treat ``--robust`` / ``--resume-mode`` as compatibility paths
+- Download state files are now stored in ``.phidown/download_state.json`` subdirectory to keep metadata separate from downloaded products
+
+### Fixed
+- Resolved a download mode precedence bug where ``resume_mode='off'`` could override
+  an explicitly provided ``mode='safe'``, causing downloads to run in non-resumable
+  ``fast`` mode unexpectedly.
+- Product footprint plotting now accepts non-polygon AOIs that are valid in the search API
+- Download retries no longer re-prompt credentials on every attempt when ``--reset`` is used
+
 [0.1.22] - 2025-10-18
 ---------------------