- rework the sphinx customizations into distinct modules

- build a new Sphinx extension that allows dialect info
to be entered as directives which is then rendered consistently
throughout all dialect/dbapi sections
- break out the "empty_strings" requirement for oracle test

3 files changed, 20 insertions, 24 deletions

diff --git a/lib/sqlalchemy/dialects/oracle/base.py b/lib/sqlalchemy/dialects/oracle/base.py
index ee4a82115..7b1470f63 100644
--- a/lib/sqlalchemy/dialects/oracle/base.py
+++ b/lib/sqlalchemy/dialects/oracle/base.py
@@ -4,9 +4,11 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
-"""Support for the Oracle database.
+"""
+.. dialect:: oracle
+    :name: Oracle
 
-Oracle version 8 through current (11g at the time of this writing) are supported.
+    Oracle version 8 through current (11g at the time of this writing) are supported.
 
 Connect Arguments
 -----------------
diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py
index ddd61e5a9..233f3cb27 100644
--- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py
+++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py
@@ -4,24 +4,19 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
-"""Support for the Oracle database via the cx_oracle driver.
-
-Driver
-------
+"""
 
-The Oracle dialect uses the cx_oracle driver, available at
-http://cx-oracle.sourceforge.net/ .   The dialect has several behaviors
-which are specifically tailored towards compatibility with this module.
-Version 5.0 or greater is **strongly** recommended, as SQLAlchemy makes
-extensive use of the cx_oracle output converters for numeric and
-string conversions.
+.. dialect:: oracle+cx_oracle
+    :name: cx-Oracle
+    :dbapi: cx_oracle
+    :connectstring: oracle+cx_oracle://user:pass@host:port/dbname[?key=value&key=value...]
+    :url: http://cx-oracle.sourceforge.net/
 
-Connecting
-----------
+Additional Connect Arguments
+----------------------------
 
-Connecting with create_engine() uses the standard URL approach of
-``oracle://user:pass@host:port/dbname[?key=value&key=value...]``.  If dbname is
-present, the host, port, and dbname tokens are converted to a TNS name using
+When connecting with ``dbname`` present, the host, port, and dbname tokens are
+converted to a TNS name using
 the cx_oracle :func:`makedsn()` function.  Otherwise, the host token is taken
 directly as a TNS name.
 
diff --git a/lib/sqlalchemy/dialects/oracle/zxjdbc.py b/lib/sqlalchemy/dialects/oracle/zxjdbc.py
index 3a0f45665..54608969b 100644
--- a/lib/sqlalchemy/dialects/oracle/zxjdbc.py
+++ b/lib/sqlalchemy/dialects/oracle/zxjdbc.py
@@ -4,13 +4,12 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
-"""Support for the Oracle database via the zxjdbc JDBC connector.
-
-JDBC Driver
------------
-
-The official Oracle JDBC driver is at
-http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html.
+"""
+.. dialect:: oracle+zxjdbc
+    :name: zxJDBC for Jython
+    :dbapi: zxjdbc
+    :connectstring: oracle+zxjdbc://user:pass@host/dbname
+    :driverurl: http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html.
 
 """
 import decimal