[Deelay1403]

Adds a "Writing Files" section to docs/getting_started/getting_started.rst, as requested in #584, plus a short example of reading from cloud storage under "Reading Files".

#910 already covered writing to an io.BytesIO buffer in the convert_to_raster example, and its commit message says it also solves #584. The issue is still open, though, and Getting Started still has no section on writing. This PR adds that section, links to the convert_to_raster example instead of repeating it, and documents writing straight to cloud storage through /vsis3/, which needs a GDAL option that isn't mentioned anywhere in the docs yet. If you'd rather close #584 as done by #910, I'm happy to trim this to only the /vsis3/ part.

The new section covers:

• GeoTIFF: rio.to_raster("out.tif"), and passing GDAL creation options such as compress="LZW".

• Cloud Optimized GeoTIFF: rio.to_raster("out_cog.tif", driver="COG").

• Cloud storage, both of which rio.to_raster supports today:

  • a GDAL virtual file system path (/vsis3/...) inside rasterio.Env(CPL_VSIL_USE_TEMP_FILE_FOR_RANDOM_WRITE="YES"). /vsis3/ only supports sequential writes, so without this option GDAL refuses to create the GeoTIFF/COG (w+b not supported for /vsis3/).
  • a file-like object (io.BytesIO, or a file opened with fsspec.open(..., "wb")). driver has to be passed explicitly here, because without it to_raster tries to infer the driver from the path and fails with a TypeError.

• Links to the existing convert_to_raster, COG and dask_read_write example notebooks so their content isn't repeated here.

• Closes DOC: add section on writing files in docs #584

• Tests added (docs only)

• Fully documented, including docs/history.rst for all changes and docs/rioxarray.rst for new API

How this was verified

Local environment: Windows 11, Python 3.13, rasterio 1.5.2 (GDAL 3.12.2 wheel), xarray 2026.9.0, rioxarray installed with pip install -e . from this branch.

• I pulled every new code-block out of the .rst file and ran it unchanged against a small synthetic 2-band float32 GeoTIFF (EPSG:32615, nodata -9999). Each output was opened again and checked for identical data, CRS and nodata. The COG outputs report LAYOUT=COG.
• The cloud snippets (xarray.open_dataset("s3://..."), the /vsis3/ write and the fsspec + s3fs write) ran against a local moto S3 server, with GDAL pointed at it via AWS_S3_ENDPOINT/AWS_HTTPS=NO/AWS_VIRTUAL_HOSTING=FALSE. They were not tested against real AWS S3, and /vsigs/ and /vsiaz/ were not tested at all. The text only says they "work similarly", following the GDAL docs.
• sphinx-build -b html -E -w warnings.txt docs <out> (Sphinx 9.2, nbsphinx 0.9.8, nbsphinx_execute = "never", pandoc from conda-forge) finishes with 0 warnings on this branch, and also on master. The new :doc:/:ref: links resolve.
• blacken-docs makes no changes.

🤖 Generated with Claude Code

[snowman2]

Thank you for your contribution. I would rather this be referenced in the getting started page from a separate page on file io.

[Deelay1403]

Thanks for the feedback! I’ve moved the content to a new page, docs/getting_started/file_io.rst, which is now linked from the getting started page and added to its toctree.

For now the new page only holds what this PR added: reading from cloud storage, plus writing GeoTIFF/COG and writing to cloud storage. The basic “Reading Files” content (xarray.open_dataset / rioxarray.open_rasterio, and why to use open_rasterio) is still in getting started.

Would you like me to move that existing reading section to the file I/O page too, so all file I/O is in one place and getting started just gives a short intro with a link? Or should the basics stay in getting started? I’m also happy to rename the page or move it somewhere else in the docs if you prefer.

[snowman2]

Suggested change

	xds = rioxarray.open_rasterio("my.tif")
	xds.rio.to_raster("out.tif")
	xds.rio.to_raster("out_lzw.tif", compress="LZW")
	with rioxarray.open_rasterio("my.tif") as xds:
	xds.rio.to_raster("out.tif")
	xds.rio.to_raster("out_lzw.tif", compress="DEFLATE")

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.91%. Comparing base (ae6635a) to head (9bfaea5).
⚠️ Report is 236 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff            @@
##           master     #952    +/-   ##
========================================
  Coverage   95.90%   95.91%            
========================================
  Files          12       18     +6     
  Lines        1735     2106   +371     
========================================
+ Hits         1664     2020   +356     
- Misses         71       86    +15     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[snowman2]

Or should the basics stay in getting started?

I think leaving the basics in getting started makes sense.