Merge pull request #268 from technige/1.7-api-docs

[1.7.1] Updates for API docs

Author: technige

make_docs.sh renamed to bin/make-docs

@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
 
-HOME=$(dirname $0)
+ROOT=$(dirname "$0")/..
 
-pip install --upgrade sphinx
-make -C ${HOME}/docs html
+pip install --quiet --upgrade sphinx
+make -C ${ROOT}/docs html
 
 echo ""
-INDEX_FILE="${HOME}/docs/build/html/index.html"
+INDEX_FILE="${ROOT}/docs/build/html/index.html"
 echo "Documentation index file can be found at file://$(cd "$(dirname "${INDEX_FILE}")"; pwd)/$(basename "${INDEX_FILE}")"

docs/source/conf.py

@@ -37,7 +37,6 @@
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.ifconfig',
-    'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
 ]
 

docs/source/driver.rst

@@ -13,10 +13,10 @@ Construction
 :class:`.Driver` construction can either be carried out directly or via a `classmethod` on the :class:`.GraphDatabase` class.
 
 .. autoclass:: neo4j.GraphDatabase
-   :members:
+   :members: driver
 
 .. autoclass:: neo4j.Driver(uri, **config)
-   :members:
+   :members: session, close, closed
 
 
 URI
@@ -37,14 +37,7 @@ URI scheme:
 Driver subclass:
     :class:`.DirectDriver`
 
-A Bolt :class:`.DirectDriver` is used to target a single machine.
-This may be a standalone server or could be a specific member of a cluster.
-
-Connections established by a :class:`.DirectDriver` are always made to the exact host and port detailed in the URI.
-
 .. autoclass:: neo4j.DirectDriver
-   :members:
-   :inherited-members:
 
 
 Bolt Routing
@@ -56,8 +49,6 @@ Driver subclass:
     :class:`.RoutingDriver`
 
 .. autoclass:: neo4j.RoutingDriver
-   :members:
-   :inherited-members:
 
 
 Configuration

docs/source/errors.rst

@@ -2,26 +2,42 @@
 Errors
 ******
 
-.. autoclass:: neo4j.exceptions.CypherError
-   :members:
 
-.. autoclass:: neo4j.exceptions.ProtocolError
-   :members:
+Connectivity errors
+===================
 
-.. autoclass:: neo4j.exceptions.SecurityError
-   :members:
+.. class:: neo4j.exceptions.ServiceUnavailable
 
-.. autoclass:: neo4j.exceptions.ServiceUnavailable
-   :members:
+    Raised when a database server or service is not available.
+    This may be due to incorrect configuration or could indicate a runtime failure of a database service that the driver is unable to route around.
+
+.. class:: neo4j.exceptions.SecurityError
+
+    Raised when a security issue occurs, generally around TLS or authentication.
+
+
+Cypher execution errors
+=======================
+
+.. class:: neo4j.exceptions.CypherError
+
+    Raised when the Cypher engine returns an error to the client.
+    There are many possible types of Cypher error, each identified by a unique `status code <https://neo4j.com/docs/developer-manual/current/reference/status-codes/>`_.
+
+    The three classifications of status code are supported by the three subclasses of :class:`.CypherError`, listed below:
 
 .. autoclass:: neo4j.exceptions.ClientError
-   :show-inheritance:
-   :members:
 
 .. autoclass:: neo4j.exceptions.DatabaseError
-   :show-inheritance:
-   :members:
 
 .. autoclass:: neo4j.exceptions.TransientError
-   :show-inheritance:
-   :members:
+
+
+Low-level errors
+================
+
+.. class:: neo4j.exceptions.ProtocolError
+
+    Raised when an unexpected or unsupported protocol event occurs.
+    This error generally indicates a fault with the driver or server software.
+    If you receive this error, please raise a GitHub issue or a support ticket.

docs/source/index.rst

@@ -2,7 +2,8 @@
 Neo4j Bolt Driver |version| for Python
 **************************************
 
-The Official Neo4j Driver for Python supports Neo4j 3.1 and above and requires Python version 2.7, 3.4, 3.5 or 3.6.
+The Official Neo4j Driver for Python supports Neo4j 3.2 and above and requires Python version 2.7 or 3.4+.
+Note that support for Python 2.7 will be removed in the 2.0 driver.
 
 
 Quick Example
@@ -25,20 +26,25 @@ Quick Example
         session.read_transaction(print_friends_of, "Alice")
 
 
+.. note::
+
+    While imports from ``neo4j.v1`` still work, these will be removed in the 2.0 driver.
+    It is therefore recommended to change all imports from ``neo4j.v1`` to ``neo4j``.
+
+
 Installation
 ============
 
-To install the latest stable version, use:
+To install the latest stable driver release, use:
 
 .. code:: bash
 
     pip install neo4j
 
-For the most up-to-date version (possibly unstable), use:
-
-.. code:: bash
+.. note::
 
-    pip install git+https://github.com/neo4j/neo4j-python-driver.git#egg=neo4j
+    The driver is currently released under two package names on `PyPI <https://pypi.org/>`_: ``neo4j`` and ``neo4j-driver``.
+    Installing from ``neo4j`` is recommended since ``neo4j-driver`` will be removed in a future release.
 
 
 API Documentation

docs/source/results.rst

@@ -9,12 +9,95 @@ Each result consists of header metadata, zero or more :class:`.Record` objects a
 Results also contain a buffer that automatically stores unconsumed records when results are consumed out of order.
 A :class:`.BoltStatementResult` is attached to an active connection, through a :class:`.Session`, until all its content has been buffered or consumed.
 
-.. autoclass:: neo4j.BoltStatementResult
-   :inherited-members:
-   :members:
+.. class:: neo4j.BoltStatementResult
 
-.. autoclass:: neo4j.Record
-   :members:
+    .. describe:: iter(result)
+
+    .. autoattribute:: session
+
+    .. automethod:: attached
+
+    .. automethod:: detach
+
+    .. automethod:: keys
+
+    .. automethod:: records
+
+    .. automethod:: summary
+
+    .. automethod:: consume
+
+    .. automethod:: single
+
+    .. automethod:: peek
+
+    .. automethod:: graph
+
+    .. automethod:: value
+
+    .. automethod:: values
+
+    .. automethod:: data
+
+
+.. class:: neo4j.Record
+
+    A :class:`.Record` is an immutable ordered collection of key-value
+    pairs. It is generally closer to a :py:class:`namedtuple` than to a
+    :py:class:`OrderedDict` inasmuch as iteration of the collection will
+    yield values rather than keys.
+
+    .. describe:: Record(iterable)
+
+        Create a new record based on an dictionary-like iterable.
+        This can be a dictionary itself, or may be a sequence of key-value pairs, each represented by a tuple.
+
+    .. describe:: record == other
+
+        Compare a record for equality with another value.
+        The `other` value may be any `Sequence` or `Mapping`, or both.
+        If comparing with a `Sequence`, the values are compared in order.
+        If comparing with a `Mapping`, the values are compared based on their keys.
+        If comparing with a value that exhibits both traits, both comparisons must be true for the values to be considered equal.
+
+    .. describe:: record != other
+
+        Compare a record for inequality with another value.
+        See above for comparison rules.
+
+    .. describe:: hash(record)
+
+        Create a hash for this record.
+        This will raise a :exc:`TypeError` if any values within the record are unhashable.
+
+    .. describe:: record[index]
+
+        Obtain a value from the record by index.
+        This will raise an :exc:`IndexError` if the specified index is out of range.
+
+    .. describe:: record[i:j]
+
+        Derive a sub-record based on a start and end index.
+        All keys and values within those bounds will be copied across in the same order as in the original record.
+
+    .. describe:: record[key]
+
+        Obtain a value from the record by key.
+        This will raise a :exc:`KeyError` if the specified key does not exist.
+
+    .. automethod:: get(key, default=None)
+
+    .. automethod:: value(key=0, default=None)
+
+    .. automethod:: index(key)
+
+    .. automethod:: keys
+
+    .. automethod:: values
+
+    .. automethod:: items
+
+    .. automethod:: data
 
 
 Summary Details