PySlurm · giovtorres · Apr 17, 2026 · May 14, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,90 @@
+name: Docs
+
+env:
+  SLURM_DOCKER_IMAGE: giovtorres/slurm-docker:25.11.4-rl10
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  docs-build:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Pull Slurm container
+        run: docker pull ${{ env.SLURM_DOCKER_IMAGE }}
+
+      - name: Start Slurm container
+        run: docker compose up -d
+
+      - name: Build docs
+        run: docker exec slurmctl bash -ec "cd /pyslurm && scripts/builddocs.sh -j4 -s"
+
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-site
+          path: site/
+          retention-days: 7
+          if-no-files-found: error
+
+  docs-deploy-dev:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Pull Slurm container
+        run: docker pull ${{ env.SLURM_DOCKER_IMAGE }}
+
+      - name: Start Slurm container
+        run: docker compose up -d
+
+      - name: Deploy dev docs
+        run: docker exec slurmctl bash -ec "cd /pyslurm && pip install -q ".[docs]" && scripts/build.sh -j4 -d && mike deploy dev --push --update-aliases"
+
+  docs-deploy-release:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Pull Slurm container
+        run: docker pull ${{ env.SLURM_DOCKER_IMAGE }}
+
+      - name: Start Slurm container
+        run: docker compose up -d
+
+      - name: Deploy versioned docs
+        run: docker exec slurmctl bash -ec "cd /pyslurm && pip install -q ".[docs]" && scripts/build.sh -j4 -d && mike deploy ${{ github.ref_name }} latest --update-aliases --push"
diff --git a/doc_requirements.txt b/doc_requirements.txt
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,86 @@
+---
+title: Getting Started
+---
+
+# Getting Started
+
+## Prerequisites
+
+- Slurm 25.11.x running with `slurmctld` accessible from the host
+- Python 3.6+
+- PySlurm installed (`pip install pyslurm` or [built from source](index.md))
+
+## List all jobs
+
+```python
+import pyslurm
+
+jobs = pyslurm.Jobs.load()
+for job_id, job in jobs.items():
+    print(f"{job_id}: {job.name} [{job.state}] user={job.user_name}")
+```
+
+## Load a single job
+
+```python
+import pyslurm
+
+job = pyslurm.Job.load(12345)
+print(job.name, job.state, job.allocated_nodes)
+```
+
+## Submit a job
+
+```python
+import pyslurm
+
+desc = pyslurm.JobSubmitDescription(
+    name="myjob",
+    script="#!/bin/bash\nhostname",
+    time_limit="01:00:00",
+    ntasks=4,
+)
+job_id = desc.submit()
+print(f"Submitted job {job_id}")
+```
+
+## List nodes
+
+```python
+import pyslurm
+
+nodes = pyslurm.Nodes.load()
+for name, node in nodes.items():
+    print(f"{name}: {node.state} cpus={node.total_cpus} mem={node.real_memory}MB")
+```
+
+## List partitions
+
+```python
+import pyslurm
+
+partitions = pyslurm.Partitions.load()
+for name, part in partitions.items():
+    print(f"{name}: {part.state} nodes={part.total_nodes}")
+```
+
+## Error handling
+
+All Slurm RPC calls raise [`pyslurm.RPCError`][pyslurm.RPCError] on failure:
+
+```python
+import pyslurm
+
+try:
+    job = pyslurm.Job.load(99999)
+except pyslurm.RPCError as e:
+    print(f"Failed: {e}")
+```
+
+## Next steps
+
+- [Job API](reference/job.md)
+- [Node API](reference/node.md)
+- [Partition API](reference/partition.md)
+- [Database API](reference/db/index.md)
+- [slurmctld API](reference/slurmctld.md)
diff --git a/docs/migration.md b/docs/migration.md
@@ -0,0 +1,60 @@
+---
+title: Migrating from the Old API
+---
+
+# Migrating from the Old API
+
+PySlurm 25.11 removed the long-deprecated legacy API classes. This page lists
+each removed class and its replacement.
+
+## Removed classes and their replacements
+
+| Removed | Replacement |
+|---------|-------------|
+| `pyslurm.job` | [`pyslurm.Job`][pyslurm.Job], [`pyslurm.Jobs`][pyslurm.Jobs], [`pyslurm.JobSubmitDescription`][pyslurm.JobSubmitDescription] |
+| `pyslurm.node` | [`pyslurm.Node`][pyslurm.Node], [`pyslurm.Nodes`][pyslurm.Nodes] |
+| `pyslurm.jobstep` | [`pyslurm.JobStep`][pyslurm.JobStep], [`pyslurm.JobSteps`][pyslurm.JobSteps] |
+| `pyslurm.partition` | [`pyslurm.Partition`][pyslurm.Partition], [`pyslurm.Partitions`][pyslurm.Partitions] |
+| `pyslurm.reservation` | [`pyslurm.Reservation`][pyslurm.Reservation], [`pyslurm.Reservations`][pyslurm.Reservations] |
+| `pyslurm.statistics` | `pyslurm.slurmctld.diag()` → [`pyslurm.slurmctld.Statistics`][pyslurm.slurmctld.Statistics] |
+| `pyslurm.front_end` | Removed from Slurm — no replacement |
+| `pyslurm.config` | [`pyslurm.slurmctld.Config`][pyslurm.slurmctld.Config] |
+
+## Loading data
+
+Old API used `get_*()` module-level functions. The new API uses classmethods:
+
+```python
+# Old
+import pyslurm
+jobs = pyslurm.job().get()
+
+# New
+import pyslurm
+jobs = pyslurm.Jobs.load()
+```
+
+## Iterating
+
+```python
+# Old
+for job_id, attrs in pyslurm.job().get().items():
+    print(job_id, attrs["job_state"])
+
+# New
+for job in pyslurm.Jobs.load().values():
+    print(job.id, job.state)
+```
+
+## Submitting a job
+
+```python
+# Old
+import pyslurm
+job_id = pyslurm.job().submit_batch_job(0, {"name": "myjob", "script": "#!/bin/bash\nhostname"})
+
+# New
+import pyslurm
+desc = pyslurm.JobSubmitDescription(name="myjob", script="#!/bin/bash\nhostname")
+job_id = desc.submit()
+```
diff --git a/docs/reference/enums.md b/docs/reference/enums.md
@@ -0,0 +1,5 @@
+---
+title: Enums
+---
+
+::: pyslurm.SchedulerType
diff --git a/docs/reference/frontend.md b/docs/reference/frontend.md
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -2,27 +2,9 @@
 
 The `pyslurm` package is a wrapper around the Slurm C-API
 
-
-!!! warning
-    Please note that the `pyslurm` API is currently being completely reworked.
-    Reworked classes and functions that replace functionality of the old API
-    will be marked as such, with a link to the documentation of its old
-    counterpart.
-
-    Old API functionality that is already replaced is marked as deprecated,
-    and will be removed at some point in the future.
-
-    The new reworked classes will be tested thoroughly before making them
-    available here, although it is of course still possible that some bugs may
-    appear here and there, which we will try to identify as best as possible!
-
-    In addition, since these classes are pretty new, their interface
-    (precisely: attribute names, return types) should not yet be considered
-    100% stable, and changes may be made in rare cases if it makes sense to do
-    so.
-
-    If you are using the new-style API, we would like to know your feedback on
-    it!
+!!! note
+    The pyslurm API was fully reworked in v25.11.0. If you are upgrading from
+    an older version, see the [Migration Guide](../migration.md).
 
 
 ## Reworked Classes

diff --git a/docs/reference/job.md b/docs/reference/job.md
@@ -2,9 +2,10 @@
 title: Job
 ---
 
-!!! note
-    This supersedes the [pyslurm.job](old/job.md) class, which will be
-    removed in a future release
+The `Job` class represents a single job in the Slurm workload manager.
+Use [`Jobs.load`][pyslurm.Jobs.load] to fetch all jobs or [`Job.load`][pyslurm.Job.load]
+for a single job by ID. To submit new jobs, see [`JobSubmitDescription`][pyslurm.JobSubmitDescription].
+For the steps within a running job, see [JobStep](jobstep.md).
 
 ::: pyslurm.Job
 ::: pyslurm.Jobs
diff --git a/docs/reference/jobstep.md b/docs/reference/jobstep.md
@@ -2,9 +2,11 @@
 title: JobStep
 ---
 
-!!! note
-    This supersedes the [pyslurm.jobstep](old/jobstep.md) class, which
-    will be removed in a future release
+The `JobStep` class represents a single step within a Slurm job — typically
+an `srun` invocation inside a batch script. Steps are automatically populated
+on the parent [`Job`][pyslurm.Job] when calling [`Job.load`][pyslurm.Job.load]
+for a running job, and are accessible via `job.steps`. See [Job](job.md) for
+the parent job API.
 
 ::: pyslurm.JobStep
 ::: pyslurm.JobSteps
diff --git a/docs/reference/node.md b/docs/reference/node.md
@@ -2,9 +2,11 @@
 title: Node
 ---
 
-!!! note
-    This supersedes the [pyslurm.node](old/node.md) class, which will be
-    removed in a future release
+The `Node` class represents a compute node registered with the Slurm controller.
+Use [`Nodes.load`][pyslurm.Nodes.load] to fetch all nodes or
+[`Node.load`][pyslurm.Node.load] for a single node by name.
+Nodes can be drained, modified, created, or deleted using the write methods.
+For partition membership, see [Partition](partition.md).
 
 ::: pyslurm.Node
 ::: pyslurm.Nodes
diff --git a/docs/reference/old/.pages b/docs/reference/old/.pages
diff --git a/docs/reference/old/db/.pages b/docs/reference/old/db/.pages
diff --git a/docs/reference/old/db/job.md b/docs/reference/old/db/job.md
diff --git a/docs/reference/old/job.md b/docs/reference/old/job.md
diff --git a/docs/reference/old/jobstep.md b/docs/reference/old/jobstep.md
diff --git a/docs/reference/old/node.md b/docs/reference/old/node.md