diff --git a/docsrc/Connecting_and_queries.rst b/docsrc/Connecting_and_queries.rst index 2250bf3e63b..18c47696e6d 100644 --- a/docsrc/Connecting_and_queries.rst +++ b/docsrc/Connecting_and_queries.rst @@ -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 ` for more details. | +------------------------------------+---------------------------------------------------------------------------------------------------------------+ @@ -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. | +------------------------------------+---------------------------------------------------------------------------------------------------------------+ @@ -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 ://:. | - | | Defaults to "http://localhost:3473" if not specified. | + | ``url`` | Optional. The URL of the Firebolt Core instance of form ://:. | + | | Defaults to "http://localhost:3473" if not specified. | +------------------------------------+---------------------------------------------------------------------------------------------------------------+ Here's how to create a connection to Firebolt Core: @@ -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`. @@ -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: diff --git a/docsrc/Managing_resources.rst b/docsrc/Managing_resources.rst index 66d6045e21d..1871a59c4d8 100644 --- a/docsrc/Managing_resources.rst +++ b/docsrc/Managing_resources.rst @@ -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` :: diff --git a/docsrc/_static/custom.css b/docsrc/_static/custom.css new file mode 100644 index 00000000000..035043730e6 --- /dev/null +++ b/docsrc/_static/custom.css @@ -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%; +} diff --git a/docsrc/conf.py b/docsrc/conf.py index 34c4a894ff9..859674fd73c 100644 --- a/docsrc/conf.py +++ b/docsrc/conf.py @@ -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) diff --git a/docsrc/firebolt.async_db.rst b/docsrc/firebolt.async_db.rst index 08a504d13b2..adacbe0e613 100644 --- a/docsrc/firebolt.async_db.rst +++ b/docsrc/firebolt.async_db.rst @@ -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: diff --git a/docsrc/firebolt.client.rst b/docsrc/firebolt.client.rst index d27ead79456..40f7f139e04 100644 --- a/docsrc/firebolt.client.rst +++ b/docsrc/firebolt.client.rst @@ -12,7 +12,7 @@ Auth :undoc-members: :show-inheritance: -Client +HTTP clients ----------------------------- .. automodule:: firebolt.client.client diff --git a/docsrc/firebolt.db.rst b/docsrc/firebolt.db.rst index 5bc47346258..2307f5f5a76 100644 --- a/docsrc/firebolt.db.rst +++ b/docsrc/firebolt.db.rst @@ -17,6 +17,7 @@ Connection .. automodule:: firebolt.db.connection :members: + :exclude-members: connect :inherited-members: :undoc-members: :show-inheritance: diff --git a/docsrc/firebolt.model.rst b/docsrc/firebolt.model.rst index 671014066df..3f4af167ff2 100644 --- a/docsrc/firebolt.model.rst +++ b/docsrc/firebolt.model.rst @@ -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: @@ -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: @@ -30,7 +30,7 @@ Engine Instance type ------------------------------------ -.. automodule:: firebolt.model.instance_type +.. automodule:: firebolt.model.V2.instance_type :members: :exclude-members: InstanceTypeKey :undoc-members: diff --git a/docsrc/firebolt.service.rst b/docsrc/firebolt.service.rst index add37e88194..fee549d9106 100644 --- a/docsrc/firebolt.service.rst +++ b/docsrc/firebolt.service.rst @@ -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: @@ -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: @@ -25,7 +25,7 @@ Database Engine ------------------------------ -.. automodule:: firebolt.service.engine +.. automodule:: firebolt.service.V2.engine :members: :undoc-members: :show-inheritance: @@ -33,7 +33,7 @@ Engine Instance type -------------------------------------- -.. automodule:: firebolt.service.instance_type +.. automodule:: firebolt.service.V2.instance_type :members: :exclude-members: InstanceTypeLookup :undoc-members: @@ -50,7 +50,7 @@ Manager Types ----------------------------- -.. automodule:: firebolt.service.types +.. automodule:: firebolt.service.V2.types :members: :undoc-members: :show-inheritance: