Did some more work on DBAL ReST documentation.

reference/en/index.rst → en/index.rst

@@ -9,25 +9,24 @@ Welcome to Doctrine DBAL's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :numbered:
 
-   introduction
-   architecture
-   configuration
-   data-retrieval-and-manipulation
-   transactions
-   platforms
-   types
-   schema-manager
-   schema-representation
-   events
-   supporting-other-databases
-   known-vendor-issues
+   reference/introduction
+   reference/architecture
+   reference/configuration
+   reference/data-retrieval-and-manipulation
+   reference/transactions
+   reference/platforms
+   reference/types
+   reference/schema-manager
+   reference/schema-representation
+   reference/events
+   reference/supporting-other-databases
+   reference/known-vendor-issues
 
 Indices and tables
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 

reference/en/configuration.rst → en/reference/configuration.rst

@@ -7,7 +7,7 @@ Getting a Connection
 You can get a DBAL Connection through the
 ``Doctrine\DBAL\DriverManager`` class.
 
-::
+.. code-block:: php
 
     <?php
     $config = new \Doctrine\DBAL\Configuration();
@@ -143,7 +143,6 @@ Custom Driver Options
 
 The ``driverOptions`` option allows to pass arbitrary options
 through to the driver. This is equivalent to the 4th argument of
-the
-`PDO constructor <http://php.net/manual/en/pdo.construct.php>`_.
+the `PDO constructor <http://php.net/manual/en/pdo.construct.php>`_.
 
 

reference/en/data-retrieval-and-manipulation.rst → en/reference/data-retrieval-and-manipulation.rst

@@ -12,7 +12,7 @@ prepare()
 Prepare a given sql statement and return the
 ``\Doctrine\DBAL\Driver\Statement`` instance:
 
-::
+.. code-block:: php
 
     <?php
     $statement = $conn->prepare('SELECT * FROM user');
@@ -34,7 +34,7 @@ executeUpdate()
 Executes a prepared statement with the given sql and parameters and
 returns the affected rows count:
 
-::
+.. code-block:: php
 
     <?php
     $count = $conn->executeUpdate('UPDATE user SET username = ? WHERE id = ?', array('jwage', 1));
@@ -51,7 +51,7 @@ executeQuery()
 Creates a prepared statement for the given sql and passes the
 parameters to the execute method, then returning the statement:
 
-::
+.. code-block:: php
 
     <?php
     $statement = $conn->execute('SELECT * FROM user WHERE username = ?', array('jwage'));
@@ -74,7 +74,7 @@ fetchAll()
 
 Execute the query and fetch all results into an array:
 
-::
+.. code-block:: php
 
     <?php
     $users = $conn->fetchAll('SELECT * FROM user');
@@ -93,7 +93,7 @@ fetchArray()
 
 Numeric index retrieval of first result row of the given query:
 
-::
+.. code-block:: php
 
     <?php
     $user = $conn->fetchArray('SELECT * FROM user WHERE username = ?', array('jwage'));
@@ -110,7 +110,7 @@ fetchColumn()
 
 Retrieve only the given column of the first result row.
 
-::
+.. code-block:: php
 
     <?php
     $username = $conn->fetchColumn('SELECT username FROM user WHERE id = ?', array(1), 0);
@@ -121,7 +121,7 @@ fetchAssoc()
 
 Retrieve assoc row of the first result row.
 
-::
+.. code-block:: php
 
     <?php
     $user = $conn->fetchAssoc('SELECT * FROM user WHERE username = ?', array('jwage'));
@@ -140,7 +140,7 @@ delete()
 Delete all rows of a table matching the given identifier, where
 keys are column names.
 
-::
+.. code-block:: php
 
     <?php
     $conn->delete('user', array('id' => 1));
@@ -152,7 +152,7 @@ insert()
 Insert a row into the given table name using the key value pairs of
 data.
 
-::
+.. code-block:: php
 
     <?php
     $conn->insert('user', array('username' => 'jwage'));
@@ -164,7 +164,7 @@ update()
 Update all rows for the matching key value identifiers with the
 given data.
 
-::
+.. code-block:: php
 
     <?php
     $conn->update('user', array('username' => 'jwage'), array('id' => 1));
@@ -182,7 +182,7 @@ quote()
 
 Quote a value:
 
-::
+.. code-block:: php
 
     <?php
     $quoted = $conn->quote('value');
@@ -193,7 +193,7 @@ quoteIdentifier()
 
 Quote an identifier according to the platform details.
 
-::
+.. code-block:: php
 
     <?php
     $quoted = $conn->quoteIdentifier('id');

reference/en/events.rst → en/reference/events.rst

@@ -32,7 +32,7 @@ Doctrine is already shipped with two implementations for the
 You can register events by subscribing them to the ``EventManager``
 instance passed to the Connection factory:
 
-::
+.. code-block:: php
 
     <?php
     $evm = new EventManager();

reference/en/introduction.rst → en/reference/introduction.rst

@@ -19,7 +19,7 @@ the ``Doctrine\Common`` and ``Doctrine\DBAL`` namespaces. Once you
 have the Common and DBAL namespaces you must setup a class loader
 to be able to autoload the classes:
 
-::
+.. code-block:: php
 
     <?php
     use Doctrine\Common\ClassLoader;

reference/en/known-vendor-issues.rst → en/reference/known-vendor-issues.rst

@@ -105,15 +105,15 @@ OCI8: SQL Queries with Question Marks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We had to implement a question mark to named parameter translation
-inside the OCI8 DBAL Driver. This means that you cannot execute
-queries that contain question marks in the SQL string. For
-example:
+inside the OCI8 DBAL Driver. It works as a very simple parser with two states: Inside Literal, Outside Literal.
+From our perspective it should be working in all cases, but you have to be careful with certain
+queries:
 
 .. code-block:: sql
 
     SELECT * FROM users WHERE name = 'bar?'
 
-Will be rewritten into:
+Could in case of a bug with the parser be rewritten into:
 
 .. code-block:: sql
 
@@ -123,17 +123,13 @@ For this reason you should always use prepared statements with
 Oracle OCI8, never use string literals inside the queries. A query
 for the user 'bar?' should look like:
 
-::
+.. code-block:: php
 
     $sql = 'SELECT * FROM users WHERE name = ?'
     $stmt = $conn->prepare($sql);
     $stmt->bindValue(1, 'bar?');
     $stmt->execute();
 
-We will probably fix this issue in the future by implementing a
-little parser inside the OCI8 Driver that can detect the difference
-between question mark needles and literal questions marks.
-
 OCI-LOB instances
 ~~~~~~~~~~~~~~~~~
 

reference/en/schema-manager.rst → en/reference/schema-manager.rst

@@ -8,7 +8,7 @@ and Indexes.
 To retrieve the ``SchemaManager`` for your connection you can use
 the ``getSchemaManager()`` method:
 
-::
+.. code-block:: php
 
     <?php
     $sm = $conn->getSchemaManager();
@@ -31,7 +31,7 @@ listDatabases()
 
 Retrieve an array of databases on the configured connection:
 
-::
+.. code-block:: php
 
     <?php
     $databases = $sm->listDatabases();
@@ -42,21 +42,21 @@ listSequences()
 Retrieve an array of ``Doctrine\DBAL\Schema\Sequence`` instances
 that exist for a database:
 
-::
+.. code-block:: php
 
     <?php
     $sequences = $sm->listSequences();
 
 Or if you want to manually specify a database name:
 
-::
+.. code-block:: php
 
     <?php
     $sequences = $sm->listSequences('dbname');
 
 Now you can loop over the array inspecting each sequence object:
 
-::
+.. code-block:: php
 
     <?php
     foreach ($sequences as $sequence) {
@@ -69,14 +69,14 @@ listTableColumns()
 Retrieve an array of ``Doctrine\DBAL\Schema\Column`` instances that
 exist for the given table:
 
-::
+.. code-block:: php
 
     <?php
     $columns = $sm->listTableColumns('user');
 
 Now you can loop over the array inspecting each column object:
 
-::
+.. code-block:: php
 
     <?php
     foreach ($columns as $column) {
@@ -89,7 +89,7 @@ listTableDetails()
 Retrieve a single ``Doctrine\DBAL\Schema\Table`` instance that
 encapsulates all the details of the given table:
 
-::
+.. code-block:: php
 
     <?php
     $table = $sm->listTableDetails('user');
@@ -97,7 +97,7 @@ encapsulates all the details of the given table:
 Now you can call methods on the table to manipulate the in memory
 schema for that table. For example we can add a new column:
 
-::
+.. code-block:: php
 
     <?php
     $table->addColumn('email_address', 'string');
@@ -108,7 +108,7 @@ listTableForeignKeys()
 Retrieve an array of ``Doctrine\DBAL\Schema\ForeignKeyConstraint``
 instances that exist for the given table:
 
-::
+.. code-block:: php
 
     <?php
     $foreignKeys = $sm->listTableForeignKeys('user');
@@ -116,7 +116,7 @@ instances that exist for the given table:
 Now you can loop over the array inspecting each foreign key
 object:
 
-::
+.. code-block:: php
 
     <?php
     foreach ($foreignKeys as $foreignKey) {
@@ -129,14 +129,14 @@ listTableIndexes()
 Retrieve an array of ``Doctrine\DBAL\Schema\Index`` instances that
 exist for the given table:
 
-::
+.. code-block:: php
 
     <?php
     $indexes = $sm->listTableIndexes('user');
 
 Now you can loop over the array inspecting each index object:
 
-::
+.. code-block:: php
 
     <?php
     foreach ($indexes as $index) {
@@ -149,7 +149,7 @@ listTables()
 Retrieve an array of ``Doctrine\DBAL\Schema\Table`` instances that
 exist in the connections database:
 
-::
+.. code-block:: php
 
     <?php
     $tables = $sm->listTables();
@@ -159,7 +159,7 @@ information provided by all the above methods. So it encapsulates
 an array of ``Doctrine\DBAL\Schema\Column`` instances that can be
 retrieved with the ``getColumns()`` method:
 
-::
+.. code-block:: php
 
     <?php
     foreach ($tables as $table) {
@@ -175,14 +175,14 @@ listViews()
 Retrieve an array of ``Doctrine\DBAL\Schema\View`` instances that
 exist in the connections database:
 
-::
+.. code-block:: php
 
     <?php
     $views = $sm->listViews();
 
 Now you can loop over the array inspecting each view object:
 
-::
+.. code-block:: php
 
     <?php
     foreach ($views as $view) {
@@ -197,7 +197,7 @@ the ``createSchema()`` method which returns an instance of
 ``Doctrine\DBAL\Schema\Schema``, which you can use in conjunction
 with the SchemaTool or Schema Comparator.
 
-::
+.. code-block:: php
 
     <?php
     $fromSchema = $sm->createSchema();
@@ -205,7 +205,7 @@ with the SchemaTool or Schema Comparator.
 Now we can clone the ``$fromSchema`` to ``$toSchema`` and drop a
 table:
 
-::
+.. code-block:: php
 
     <?php
     $toSchema = clone $fromSchema;
@@ -215,7 +215,7 @@ Now we can compare the two schema instances in order to calculate
 the differences between them and return the sql required to make
 the changes on the database:
 
-::
+.. code-block:: php
 
     <?php
     $sql = $fromSchema->getMigrateToSql($toSchema, $conn->getDatabasePlatform());
@@ -223,7 +223,7 @@ the changes on the database:
 The ``$sql`` array should give you a sql query to drop the user
 table:
 
-::
+.. code-block:: php
 
     <?php
     print_r($sql);

reference/en/schema-representation.rst → en/reference/schema-representation.rst

@@ -19,7 +19,7 @@ or for SQL schema generation for any metadata model that your
 application has. You can easily generate a Schema, as a simple
 example shows:
 
-::
+.. code-block:: php
 
     <?php
     $schema = new \Doctrine\DBAL\Schema\Schema();
@@ -43,7 +43,7 @@ use the ``Comparator`` class to get instances of ``SchemaDiff``,
 ``TableDiff`` and ``ColumnDiff``, aswell as information about other
 foreign key, sequence and index changes.
 
-::
+.. code-block:: php
 
     <?php
     $comparator = new \Doctrine\DBAL\Schema\Comparator();

reference/en/transactions.rst → en/reference/transactions.rst

@@ -124,17 +124,18 @@ All that is guaruanteed to the inner transaction is that it still
 happens atomically, all or nothing, the transaction just gets a
 wider scope and the control is handed to the outer scope.
 
-    **CAUTION** The transaction nesting described here is a debated
+.. note::
+
+    The transaction nesting described here is a debated
     feature that has it's critics. Form your own opinion. We recommend
     avoiding nesting transaction blocks when possible, and most of the
     time, it is possible. Transaction control should mostly be left to
     a service layer and not be handled in data access objects or
     similar.
 
+.. warning::
 
--
-
-    **CAUTION** Directly invoking ``PDO#beginTransaction()``,
+    Directly invoking ``PDO#beginTransaction()``,
     ``PDO#commit()`` or ``PDO#rollback()`` or the corresponding methods
     on the particular ``Doctrine\DBAL\Driver\Connection`` instance in
     use bybasses the transparent transaction nesting that is provided

generate-docs.sh

 #!/bin/bash
-sphinx-build reference/en /var/www/docs
\ No newline at end of file
+sphinx-build en /var/www/docs