Skip to content

Commit e8d1053

Browse files
sid-rlsid-rl
authored
feat(docs): add documentation for the object oriented sdk, rendered with sphinx (#677)
* ignore generated docs files * feat(docs): add autogenerated sphinx docs to github pages (#676) * initial sphinx docstring conversion * change params to use :typeddict: tag * sphinx docs * sphinx github workflow * formatting fixes * fix publish dir * unnecessary argument to sphinx action * switch to manual build html command instead of ammaraskar/sphinx-action * sphinx docs rendering is triggered on published release, instead of on push. also added workflow_dispatch trigger * remove merge conflict marker
1 parent e78e3eb commit e8d1053

25 files changed

Lines changed: 2097 additions & 768 deletions

‎.github/workflows/sphinx.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: "Sphinx: Render docs"
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
permissions:
12+
contents: write
13+
steps:
14+
- uses: actions/checkout@v4
15+
with:
16+
persist-credentials: false
17+
- name: Install uv
18+
uses: astral-sh/setup-uv@v7
19+
with:
20+
version: '0.9.10'
21+
- name: Install dependencies
22+
run: uv sync --group docs
23+
- name: Build HTML
24+
working-directory: docs
25+
run: uv run make html
26+
- name: Upload artifacts
27+
uses: actions/upload-artifact@v4
28+
with:
29+
name: html-docs
30+
path: docs/_build/html/
31+
- name: Deploy
32+
uses: peaceiris/actions-gh-pages@v4
33+
if: github.ref == 'refs/heads/main'
34+
with:
35+
github_token: ${{ secrets.GITHUB_TOKEN }}
36+
publish_dir: docs/_build/html

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,7 @@ htmlcov/
2323
coverage.json
2424
coverage-summary.json
2525
*.cover
26-
.pytest_cache/
26+
.pytest_cache/
27+
28+
# Docs
29+
site/

‎docs/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_build/

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/api/index.rst‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
API Reference
2+
=============
3+
4+
This section contains detailed API documentation for the Runloop SDK.
5+
6+
.. toctree::
7+
:maxdepth: 2
8+
9+
typedicts
10+
11+
SDK Classes
12+
-----------
13+
14+
Synchronous SDK
15+
~~~~~~~~~~~~~~~
16+
17+
.. autoclass:: runloop_api_client.RunloopSDK
18+
:members:
19+
:undoc-members:
20+
:show-inheritance:
21+
22+
.. autoclass:: runloop_api_client.sdk.sync.DevboxOps
23+
:members:
24+
:undoc-members:
25+
:show-inheritance:
26+
27+
.. autoclass:: runloop_api_client.sdk.sync.BlueprintOps
28+
:members:
29+
:undoc-members:
30+
:show-inheritance:
31+
32+
.. autoclass:: runloop_api_client.sdk.sync.SnapshotOps
33+
:members:
34+
:undoc-members:
35+
:show-inheritance:
36+
37+
.. autoclass:: runloop_api_client.sdk.sync.StorageObjectOps
38+
:members:
39+
:undoc-members:
40+
:show-inheritance:
41+
42+
Resource Classes
43+
~~~~~~~~~~~~~~~~
44+
45+
.. autoclass:: runloop_api_client.sdk.devbox.Devbox
46+
:members:
47+
:undoc-members:
48+
:show-inheritance:
49+
50+
.. autoclass:: runloop_api_client.sdk.blueprint.Blueprint
51+
:members:
52+
:undoc-members:
53+
:show-inheritance:
54+
55+
.. autoclass:: runloop_api_client.sdk.snapshot.Snapshot
56+
:members:
57+
:undoc-members:
58+
:show-inheritance:
59+
60+
.. autoclass:: runloop_api_client.sdk.storage_object.StorageObject
61+
:members:
62+
:undoc-members:
63+
:show-inheritance:
64+
65+
.. autoclass:: runloop_api_client.sdk.execution.Execution
66+
:members:
67+
:undoc-members:
68+
:show-inheritance:
69+
70+
.. autoclass:: runloop_api_client.sdk.execution_result.ExecutionResult
71+
:members:
72+
:undoc-members:
73+
:show-inheritance:
74+
75+
Asynchronous SDK
76+
~~~~~~~~~~~~~~~~
77+
78+
.. autoclass:: runloop_api_client.AsyncRunloopSDK
79+
:members:
80+
:undoc-members:
81+
:show-inheritance:
82+
83+
.. autoclass:: runloop_api_client.sdk.async_.AsyncDevboxOps
84+
:members:
85+
:undoc-members:
86+
:show-inheritance:
87+
88+
.. autoclass:: runloop_api_client.sdk.async_.AsyncBlueprintOps
89+
:members:
90+
:undoc-members:
91+
:show-inheritance:
92+
93+
.. autoclass:: runloop_api_client.sdk.async_.AsyncSnapshotOps
94+
:members:
95+
:undoc-members:
96+
:show-inheritance:
97+
98+
.. autoclass:: runloop_api_client.sdk.async_.AsyncStorageObjectOps
99+
:members:
100+
:undoc-members:
101+
:show-inheritance:
102+
103+
Asynchronous Resource Classes
104+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105+
106+
.. autoclass:: runloop_api_client.sdk.async_devbox.AsyncDevbox
107+
:members:
108+
:undoc-members:
109+
:show-inheritance:
110+
111+
.. autoclass:: runloop_api_client.sdk.async_blueprint.AsyncBlueprint
112+
:members:
113+
:undoc-members:
114+
:show-inheritance:
115+
116+
.. autoclass:: runloop_api_client.sdk.async_snapshot.AsyncSnapshot
117+
:members:
118+
:undoc-members:
119+
:show-inheritance:
120+
121+
.. autoclass:: runloop_api_client.sdk.async_storage_object.AsyncStorageObject
122+
:members:
123+
:undoc-members:
124+
:show-inheritance:
125+
126+
.. autoclass:: runloop_api_client.sdk.async_execution.AsyncExecution
127+
:members:
128+
:undoc-members:
129+
:show-inheritance:
130+
131+
.. autoclass:: runloop_api_client.sdk.async_execution_result.AsyncExecutionResult
132+
:members:
133+
:undoc-members:
134+
:show-inheritance:
135+

‎docs/api/typedicts.rst‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
TypedDict Reference
2+
===================
3+
4+
This page documents all TypedDict parameter types used throughout the SDK.
5+
These typed dictionaries define the structure of parameters passed to SDK methods.
6+
7+
SDK TypedDicts
8+
--------------
9+
10+
These are the primary TypedDict classes used in SDK methods, combining multiple
11+
parameter types and options.
12+
13+
Core Request Options
14+
~~~~~~~~~~~~~~~~~~~~
15+
16+
.. autotypeddict:: runloop_api_client.sdk._types.ExecuteStreamingCallbacks
17+
18+
.. autotypeddict:: runloop_api_client.sdk._types.RequestOptions
19+
20+
.. autotypeddict:: runloop_api_client.sdk._types.LongRequestOptions
21+
22+
.. autotypeddict:: runloop_api_client.sdk._types.PollingRequestOptions
23+
24+
.. autotypeddict:: runloop_api_client.sdk._types.LongPollingRequestOptions
25+
26+
Devbox Parameters
27+
~~~~~~~~~~~~~~~~~
28+
29+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxCreateParams
30+
31+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExtraCreateParams
32+
33+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExecuteParams
34+
35+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxExecuteAsyncParams
36+
37+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxListParams
38+
39+
File Operation Parameters
40+
~~~~~~~~~~~~~~~~~~~~~~~~~
41+
42+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxReadFileContentsParams
43+
44+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxWriteFileContentsParams
45+
46+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxDownloadFileParams
47+
48+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxUploadFileParams
49+
50+
Network Operation Parameters
51+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52+
53+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxCreateTunnelParams
54+
55+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxRemoveTunnelParams
56+
57+
Snapshot Parameters
58+
~~~~~~~~~~~~~~~~~~~
59+
60+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxSnapshotDiskParams
61+
62+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDevboxSnapshotDiskAsyncParams
63+
64+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDiskSnapshotListParams
65+
66+
.. autotypeddict:: runloop_api_client.sdk._types.SDKDiskSnapshotUpdateParams
67+
68+
Blueprint Parameters
69+
~~~~~~~~~~~~~~~~~~~~
70+
71+
.. autotypeddict:: runloop_api_client.sdk._types.SDKBlueprintCreateParams
72+
73+
.. autotypeddict:: runloop_api_client.sdk._types.SDKBlueprintListParams
74+
75+
Storage Object Parameters
76+
~~~~~~~~~~~~~~~~~~~~~~~~~
77+
78+
.. autotypeddict:: runloop_api_client.sdk._types.SDKObjectCreateParams
79+
80+
.. autotypeddict:: runloop_api_client.sdk._types.SDKObjectListParams
81+
82+
.. autotypeddict:: runloop_api_client.sdk._types.SDKObjectDownloadParams

‎docs/conf.py‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
import os
7+
import sys
8+
9+
# Add the src directory to the path so we can import the package
10+
sys.path.insert(0, os.path.abspath("../src"))
11+
12+
# -- Project information -----------------------------------------------------
13+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
14+
15+
project = "Runloop Python SDK"
16+
copyright = "2025, Runloop"
17+
author = "Runloop"
18+
release = "0.68.0"
19+
20+
# -- General configuration ---------------------------------------------------
21+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
22+
23+
extensions = [
24+
"sphinx.ext.autodoc",
25+
"sphinx.ext.napoleon",
26+
"sphinx.ext.intersphinx",
27+
"sphinx.ext.viewcode",
28+
"sphinx_toolbox.more_autodoc.autotypeddict",
29+
"sphinx_autodoc_typehints",
30+
]
31+
32+
templates_path = ["_templates"]
33+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
34+
35+
# -- Options for HTML output -------------------------------------------------
36+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
37+
38+
html_theme = "furo"
39+
html_static_path = ["_static"]
40+
41+
# -- Extension configuration -------------------------------------------------
42+
43+
# Napoleon settings
44+
napoleon_google_docstring = False
45+
napoleon_numpy_docstring = False
46+
napoleon_use_param = True
47+
napoleon_use_rtype = True
48+
napoleon_use_ivar = True
49+
50+
# Autodoc settings
51+
autodoc_default_options = {
52+
"members": None,
53+
"undoc-members": None,
54+
"show-inheritance": None,
55+
}
56+
57+
autodoc_typehints = "description"
58+
autodoc_typehints_description_target = "documented"
59+
60+
# Intersphinx mapping
61+
intersphinx_mapping = {
62+
"python": ("https://docs.python.org/3", None),
63+
"httpx": ("https://www.python-httpx.org", None),
64+
}

0 commit comments

Comments
 (0)