Skip to content

fix(docs): restore Python SDK reference pages and fix rendering (FB-5346) #561

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
simonzelenskifbio wants to merge 18 commits into
base: main
Choose a base branch
from
Open

fix(docs): restore Python SDK reference pages and fix rendering (FB-5346) #561

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
f12c5a6
fix(docs): remove nonexistent async utility reference (FB-5346)
simonzelenskifbio Oct 29, 2026
297d173
fix(docs): correct database model reference (FB-5346)
simonzelenskifbio Oct 29, 2026
0f23d30
fix(docs): correct instance type model reference (FB-5346)
simonzelenskifbio Oct 29, 2026
855a855
fix(docs): correct base service reference (FB-5346)
simonzelenskifbio Oct 29, 2026
2aa3fae
fix(docs): correct database service reference (FB-5346)
simonzelenskifbio Oct 29, 2026
4449dbf
fix(docs): correct engine service reference (FB-5346)
simonzelenskifbio Oct 29, 2026
8748397
fix(docs): correct instance type service reference (FB-5346)
simonzelenskifbio Oct 29, 2026
73e42a0
fix(docs): correct types service reference (FB-5346)
simonzelenskifbio Oct 29, 2026
8baa141
fix(docs): document the V2 engine instead of its empty compatibility …
simonzelenskifbio Oct 29, 2026
9faa440
fix(docs): align managed connection parameter table borders (FB-5346)
simonzelenskifbio Oct 29, 2026
c1de524
fix(docs): align Core connection parameter table borders (FB-5346)
simonzelenskifbio Oct 29, 2026
9e22af3
fix(docs): match query result heading underline length (FB-5346)
simonzelenskifbio Oct 29, 2026
86d0d9e
fix(docs): repair asynchronous streaming literal block (FB-5346)
simonzelenskifbio Oct 29, 2026
663a787
fix(docs): give HTTP clients a unique section label (FB-5346)
simonzelenskifbio Oct 29, 2026
3b96282
fix(docs): avoid documenting connect twice (FB-5346)
simonzelenskifbio Oct 29, 2026
cf685a5
fix(docs): resolve sync and async cursor Connection references (FB-5346)
simonzelenskifbio Oct 29, 2026
535d6e7
fix(docs): wrap connection parameter table descriptions (FB-5346)
simonzelenskifbio Oct 29, 2026
2ac346d
style(docs): format Sphinx configuration with Black (FB-5346)
simonzelenskifbio Oct 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions docsrc/Connecting_and_queries.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ To get started, follow the steps below:

A connection requires the following parameters:

.. rst-class:: connection-parameters

+------------------------------------+---------------------------------------------------------------------------------------------------------------+
| ``auth`` | Auth object, containing your credentials. See :ref:`Auth <firebolt.client:auth>` for more details. |
+------------------------------------+---------------------------------------------------------------------------------------------------------------+
Expand All @@ -45,7 +47,7 @@ To get started, follow the steps below:
+------------------------------------+---------------------------------------------------------------------------------------------------------------+
| ``engine_name`` | Optional. The name of the engine to use for SQL queries. |
+------------------------------------+---------------------------------------------------------------------------------------------------------------+
| ``autocommit`` | Optional. Boolean (default: True). When True, each statement is committed immediately. |
| ``autocommit`` | Optional. Boolean (default: True). When True, each statement is committed immediately. |
| | When False, statements are executed in transactions that must be explicitly committed. |
+------------------------------------+---------------------------------------------------------------------------------------------------------------+

Expand Down Expand Up @@ -177,13 +179,15 @@ To get started, follow the steps below:

A connection requires the following parameters:

.. rst-class:: connection-parameters

+------------------------------------+---------------------------------------------------------------------------------------------------------------+
| ``auth`` | Auth object of type FireboltCore. This is a special authentication type that doesn't require credentials. |
| ``auth`` | Auth object of type FireboltCore. This is a special authentication type that doesn't require credentials. |
+------------------------------------+---------------------------------------------------------------------------------------------------------------+
| ``database`` | Optional. The name of the database you would like to connect to. Defaults to "firebolt" if not specified. |
| ``database`` | Optional. The name of the database you would like to connect to. Defaults to "firebolt" if not specified. |
+------------------------------------+---------------------------------------------------------------------------------------------------------------+
| ``url`` | Optional. The URL of the Firebolt Core instance of form <scheme>://<host>:<port>. |
| | Defaults to "http://localhost:3473" if not specified. |
| ``url`` | Optional. The URL of the Firebolt Core instance of form <scheme>://<host>:<port>. |
| | Defaults to "http://localhost:3473" if not specified. |
+------------------------------------+---------------------------------------------------------------------------------------------------------------+

Here's how to create a connection to Firebolt Core:
Expand Down Expand Up @@ -313,7 +317,7 @@ below use the data queried from ``test_table`` created in the


Fetching query result information
-----------------------
---------------------------------

After running a query, you can fetch information about the results using the same ``cursor`` object. The examples
below are from the last SELECT query in :ref:`connecting_and_queries:Inserting and selecting data`.
Expand Down Expand Up @@ -890,6 +894,7 @@ Synchronous example:

Asynchronous example:
::

async with async_connection.cursor() as cursor:
await cursor.execute_stream("SELECT * FROM my_huge_table")
async for row in cursor:
Expand Down
2 changes: 1 addition & 1 deletion docsrc/Managing_resources.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -285,7 +285,7 @@ Updating an engine
Update an engine to change its specifications, returning an updated version of the engine.
The engine must be stopped in order to be updated.

For a list of engine parameters that can be updated, see :meth:`~firebolt.model.engine.Engine.update`
For a list of engine parameters that can be updated, see :meth:`~firebolt.model.V2.engine.Engine.update`

::

Expand Down
13 changes: 13 additions & 0 deletions docsrc/_static/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
/* Wrap connection parameter descriptions within the page width. */
.wy-table-responsive table.connection-parameters {
width: 100%;
table-layout: fixed;
}
.wy-table-responsive table.connection-parameters td,
.wy-table-responsive table.connection-parameters th {
white-space: normal;
overflow-wrap: anywhere;
}
.wy-table-responsive table.connection-parameters td:first-child {
width: 25%;
}
19 changes: 18 additions & 1 deletion docsrc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,4 +64,21 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
html_static_path = ["_static"]
html_css_files = ["custom.css"]


def qualify_cursor_connections(app, doctree):
from sphinx.addnodes import pending_xref

for node in doctree.findall(pending_xref):
module = node.get("py:module", "")
if node.get("reftarget") == "Connection" and module in (
"firebolt.db.cursor",
"firebolt.async_db.cursor",
):
node["reftarget"] = module.removesuffix("cursor") + "connection.Connection"


def setup(app):
app.connect("doctree-read", qualify_cursor_connections)
8 changes: 0 additions & 8 deletions docsrc/firebolt.async_db.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,3 @@ Cursor
:exclude-members: BaseCursor, check_not_closed, check_query_executed, is_db_available, is_engine_running
:undoc-members:
:show-inheritance:

Util
------------------------------

.. automodule:: firebolt.async_db.util
:members:
:undoc-members:
:show-inheritance:
2 changes: 1 addition & 1 deletion docsrc/firebolt.client.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Auth
:undoc-members:
:show-inheritance:

Client
HTTP clients
-----------------------------

.. automodule:: firebolt.client.client
Expand Down
1 change: 1 addition & 0 deletions docsrc/firebolt.db.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ Connection

.. automodule:: firebolt.db.connection
:members:
:exclude-members: connect
:inherited-members:
:undoc-members:
:show-inheritance:
Expand Down
6 changes: 3 additions & 3 deletions docsrc/firebolt.model.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The model package contains various classes and functions for managing Firebolt e
Database
------------------------------

.. automodule:: firebolt.model.database
.. automodule:: firebolt.model.V2.database
:members:
:exclude-members: DatabaseKey, FieldMask
:undoc-members:
Expand All @@ -20,7 +20,7 @@ Database
Engine
----------------------------

.. automodule:: firebolt.model.engine
.. automodule:: firebolt.model.V2.engine
:members:
:exclude-members: EngineKey, FieldMask, check_attached_to_database, wait
:undoc-members:
Expand All @@ -30,7 +30,7 @@ Engine
Instance type
------------------------------------

.. automodule:: firebolt.model.instance_type
.. automodule:: firebolt.model.V2.instance_type
:members:
:exclude-members: InstanceTypeKey
:undoc-members:
Expand Down
10 changes: 5 additions & 5 deletions docsrc/firebolt.service.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Service

The service package enables launching and cataloging Firebolt engines and databases.

.. automodule:: firebolt.service.base
.. automodule:: firebolt.service.V2.base
:members:
:exclude-members: BaseService
:undoc-members:
Expand All @@ -15,7 +15,7 @@ The service package enables launching and cataloging Firebolt engines and databa
Database
--------------------------------

.. automodule:: firebolt.service.database
.. automodule:: firebolt.service.V2.database
:members:
:undoc-members:
:show-inheritance:
Expand All @@ -25,15 +25,15 @@ Database
Engine
------------------------------

.. automodule:: firebolt.service.engine
.. automodule:: firebolt.service.V2.engine
:members:
:undoc-members:
:show-inheritance:

Instance type
--------------------------------------

.. automodule:: firebolt.service.instance_type
.. automodule:: firebolt.service.V2.instance_type
:members:
:exclude-members: InstanceTypeLookup
:undoc-members:
Expand All @@ -50,7 +50,7 @@ Manager
Types
-----------------------------

.. automodule:: firebolt.service.types
.. automodule:: firebolt.service.V2.types
:members:
:undoc-members:
:show-inheritance:
Loading