sdimitro · sdimitro · Jan 29, 2026 · Jan 29, 2026 · Jan 29, 2026 · Jan 29, 2026
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
   <a href="https://github.com/sdimitro/kdumpling/actions/workflows/ci.yml"><img src="https://github.com/sdimitro/kdumpling/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://codecov.io/gh/sdimitro/kdumpling"><img src="https://codecov.io/gh/sdimitro/kdumpling/graph/badge.svg" alt="Codecov"></a>
   <a href="https://kdumpling.readthedocs.io"><img src="https://readthedocs.org/projects/kdumpling/badge/?version=latest" alt="Documentation"></a>
-  <a href="https://badge.fury.io/py/kdumpling"><img src="https://badge.fury.io/py/kdumpling.svg" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/kdumpling/"><img src="https://img.shields.io/pypi/v/kdumpling.svg" alt="PyPI version"></a>
   <a href="https://pypi.org/project/kdumpling/"><img src="https://img.shields.io/pypi/pyversions/kdumpling.svg" alt="Python versions"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
 </p>

diff --git a/docs/api.md b/docs/api.md
@@ -1,201 +1,49 @@
 # API Reference
 
-## KdumpBuilder
+This page is auto-generated from the source code docstrings using Sphinx autodoc.
 
-The main class for building vmcore files.
+## kdumpling module
 
-```python
-from kdumpling import KdumpBuilder
+```{eval-rst}
+.. automodule:: kdumpling
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :imported-members:
 ```
 
-### Constructor
+## kdumpling.builder module
 
-```python
-KdumpBuilder(arch: str = 'x86_64')
+```{eval-rst}
+.. automodule:: kdumpling.builder
+   :members:
+   :undoc-members:
+   :show-inheritance:
 ```
 
-**Parameters:**
-- `arch`: Target architecture. One of: `x86_64`, `aarch64`, `arm64`, `s390x`, `ppc64le`, `ppc64`, `riscv64`
+## kdumpling.cpu_context module
 
-**Raises:**
-- `ValueError`: If the architecture is not supported
-
-### Methods
-
-#### set_vmcoreinfo
-
-```python
-def set_vmcoreinfo(self, data: str | bytes) -> KdumpBuilder
-```
-
-Set the VMCOREINFO metadata string.
-
-**Parameters:**
-- `data`: The vmcoreinfo string (e.g., `"OSRELEASE=5.14.0\nPAGESIZE=4096\n"`)
-
-**Returns:** `self` for method chaining
-
-#### add_memory_segment
-
-```python
-def add_memory_segment(self, phys_addr: int, data: bytes | str | BinaryIO) -> KdumpBuilder
-```
-
-Add a memory segment to the dump.
-
-**Parameters:**
-- `phys_addr`: The physical address where this memory resides
-- `data`: The memory data. Can be:
-  - `bytes`: Raw memory content
-  - `str`: Path to a file containing the data
-  - `BinaryIO`: File-like object to read from
-
-**Returns:** `self` for method chaining
-
-#### add_cpu_context
-
-```python
-def add_cpu_context(
-    self,
-    cpu_id: int = 0,
-    registers: dict[str, int] | None = None,
-    pid: int = 0,
-    **kwargs: int
-) -> KdumpBuilder
-```
-
-Add CPU register state for a processor.
-
-**Parameters:**
-- `cpu_id`: CPU identifier (0-indexed)
-- `registers`: Dictionary mapping register names to values
-  - For x86_64: `RIP`, `RSP`, `RBP`, `RAX`, `RBX`, `RCX`, `RDX`, `RSI`, `RDI`, `R8`-`R15`, etc.
-  - For aarch64: `X0`-`X30`, `SP`, `PC`, `PSTATE`
-- `pid`: Process ID associated with this CPU
-- `**kwargs`: Additional prstatus fields (`pr_ppid`, `pr_pgrp`, `pr_sid`, `si_signo`, etc.)
-
-**Returns:** `self` for method chaining
-
-#### write
-
-```python
-def write(self, output_path: str) -> None
+```{eval-rst}
+.. automodule:: kdumpling.cpu_context
+   :members:
+   :undoc-members:
+   :show-inheritance:
 ```
 
-Write the vmcore file to disk.
+## kdumpling.elf module
 
-**Parameters:**
-- `output_path`: Path where the vmcore file will be written
-
-### Properties
-
-#### stats
-
-```python
-@property
-def stats(self) -> DumpStats
+```{eval-rst}
+.. automodule:: kdumpling.elf
+   :members:
+   :undoc-members:
+   :show-inheritance:
 ```
 
-Get statistics about the dump being built.
-
-**Returns:** `DumpStats` object with information about segments, size, etc.
-
----
-
-## DumpStats
-
-Statistics about a vmcore dump being built.
-
-```python
-from kdumpling import DumpStats
-```
-
-### Attributes
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `architecture` | `str` | Target architecture |
-| `num_memory_segments` | `int` | Number of memory segments |
-| `num_cpu_contexts` | `int` | Number of CPU contexts |
-| `total_memory_size` | `int` | Total memory size in bytes |
-| `vmcoreinfo_size` | `int` | Size of vmcoreinfo in bytes |
-| `estimated_file_size` | `int` | Estimated output file size |
-| `memory_segments` | `list[tuple[int, int]]` | List of (phys_addr, size) tuples |
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `total_memory_size_human` | `str` | Human-readable memory size (e.g., "4.0 MB") |
-| `estimated_file_size_human` | `str` | Human-readable file size |
-
-### String Representation
-
-`DumpStats` has a `__str__` method that provides a formatted summary:
-
-```python
-print(builder.stats)
-# Dump Statistics:
-#   Architecture: x86_64
-#   Memory Segments: 2
-#   CPU Contexts: 1
-#   Total Memory: 8.0 KB (8192 bytes)
-#   ...
-```
-
----
-
-## CpuContext
-
-CPU context for a single processor (used internally).
-
-```python
-from kdumpling import CpuContext
-```
-
-### Attributes
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `cpu_id` | `int` | CPU identifier |
-| `pid` | `int` | Process ID |
-| `registers` | `dict[str, int]` | Register name to value mapping |
-| `si_signo` | `int` | Signal number |
-| `pr_pid` | `int` | Process ID in prstatus |
-| `pr_ppid` | `int` | Parent process ID |
-
----
-
-## Register Enums
-
-### X86_64Reg
-
-Register indices for x86_64 architecture.
-
-```python
-from kdumpling import X86_64Reg
-
-# Available registers:
-X86_64Reg.RIP  # Instruction pointer
-X86_64Reg.RSP  # Stack pointer
-X86_64Reg.RBP  # Base pointer
-X86_64Reg.RAX, X86_64Reg.RBX, X86_64Reg.RCX, X86_64Reg.RDX
-X86_64Reg.RSI, X86_64Reg.RDI
-X86_64Reg.R8, X86_64Reg.R9, X86_64Reg.R10, X86_64Reg.R11
-X86_64Reg.R12, X86_64Reg.R13, X86_64Reg.R14, X86_64Reg.R15
-# ... and more
-```
-
-### AArch64Reg
-
-Register indices for AArch64 (ARM64) architecture.
-
-```python
-from kdumpling import AArch64Reg
+## kdumpling.kdump_compressed module
 
-# Available registers:
-AArch64Reg.X0 through AArch64Reg.X30
-AArch64Reg.SP     # Stack pointer
-AArch64Reg.PC     # Program counter
-AArch64Reg.PSTATE # Processor state
+```{eval-rst}
+.. automodule:: kdumpling.kdump_compressed
+   :members:
+   :undoc-members:
+   :show-inheritance:
 ```
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,5 +1,11 @@
 # Configuration file for the Sphinx documentation builder.
 
+import os
+import sys
+
+# Add the package to the path for autodoc
+sys.path.insert(0, os.path.abspath(".."))
+
 project = "kdumpling"
 copyright = "2024, kdumpling contributors"
 author = "kdumpling contributors"
@@ -36,3 +42,27 @@
     ".rst": "restructuredtext",
     ".md": "markdown",
 }
+
+# Autodoc configuration
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": True,
+    "exclude-members": "__weakref__",
+    "show-inheritance": True,
+}
+
+# Napoleon settings for Google/NumPy style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_type_aliases = None
diff --git a/docs/index.md b/docs/index.md
@@ -8,10 +8,6 @@
 
 A Python library for creating Linux kdump crash dump files.
 
-```{warning}
-This library is currently a work in progress. The API may change in future releases.
-```
-
 ## Overview
 
 **kdumpling** allows you to synthesize valid ELF64 vmcore files from raw memory data and vmcoreinfo values. This is useful for:

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -99,6 +99,61 @@ Dump Statistics:
     0x0000000000100000: 4.0 MB
 ```
 
+## Compressed Output
+
+kdumpling supports the kdump compressed format, which is compatible with makedumpfile and tools like crash, libkdumpfile, and drgn. This format provides per-page compression and can significantly reduce file sizes.
+
+### Basic Compressed Output
+
+```python
+from kdumpling import KdumpBuilder, OutputFormat, CompressionType
+
+builder = KdumpBuilder(arch='x86_64')
+builder.set_vmcoreinfo("OSRELEASE=5.14.0\nPAGESIZE=4096\n")
+builder.add_memory_segment(0x100000, b'\x00' * 4096 * 100)  # 400KB
+
+# Write in kdump compressed format with zlib compression
+builder.write(
+    "compressed.vmcore",
+    format=OutputFormat.KDUMP_COMPRESSED,
+    compression=CompressionType.ZLIB
+)
+```
+
+### Compression Options
+
+```python
+from kdumpling import KdumpBuilder, OutputFormat, CompressionType
+
+builder = KdumpBuilder(arch='x86_64')
+builder.set_vmcoreinfo("OSRELEASE=5.14.0\n")
+builder.add_memory_segment(0x100000, memory_data)
+
+# No compression (still filters zero pages)
+builder.write("dump.vmcore", format=OutputFormat.KDUMP_COMPRESSED,
+              compression=CompressionType.NONE)
+
+# Zlib compression (default, always available)
+builder.write("dump.vmcore", format=OutputFormat.KDUMP_COMPRESSED,
+              compression=CompressionType.ZLIB, compression_level=9)
+
+# Zstandard compression (requires 'zstandard' package)
+builder.write("dump.vmcore", format=OutputFormat.KDUMP_COMPRESSED,
+              compression=CompressionType.ZSTD)
+```
+
+### Available Compression Types
+
+| Type | Description | Requirement |
+|------|-------------|-------------|
+| `CompressionType.NONE` | No compression | None |
+| `CompressionType.ZLIB` | zlib/gzip (default) | None (built-in) |
+| `CompressionType.LZO` | LZO compression | `python-lzo` |
+| `CompressionType.SNAPPY` | Snappy compression | `python-snappy` |
+| `CompressionType.ZSTD` | Zstandard compression | `zstandard` |
+
+The compressed format automatically excludes zero-filled pages, reducing output size even without compression.
+
 ## Supported Architectures
 
 kdumpling supports the following architectures: