4.2 python driver docs improvements (#192)

Fixed navigation.
Improved config settings.

Author: martin-neotech

pythonManual/antora/content-nav.adoc

@@ -3,6 +3,6 @@
 * xref:client-applications/index.adoc[]
 * xref:cypher-workflow/index.adoc[]
 * xref:session-api/index.adoc[]
-** xref:session-api/simple/index.adoc[Simple Sessions]
-** xref:session-api/configuration/index.adoc[Session Configuration]
+** xref:session-api/index.adoc#python-driver-simple-sessions[Simple sessions]
+** xref:session-api/index.adoc#python-driver-session-configuration[Session configuration]
 * xref:terminology/index.adoc[]

pythonManual/asciidoc/client-applications.adoc

@@ -342,7 +342,20 @@ include::{python-examples}/test_custom_auth_example.py[tags=custom-auth]
 [[python-driver-configuration]]
 == Configuration
 
-include::{common-content}/client-applications.adoc[tag=configuration-ConnectionAcquisitionTimeout]
+//include::{common-content}/client-applications.adoc[tag=configuration-ConnectionAcquisitionTimeout]
+link:https://neo4j.com/docs/api/python-driver/{neo4j-version}/api.html#connection-acquisition-timeout[`ConnectionAcquisitionTimeout`]::
+
+The maximum amount of time in secondsfootnote:[Other drivers may use milliseconds instead of seconds for this configuration.] a session will wait when requesting a connection from the connection pool.
+For connection pools where all connections are currently being used and the `MaxConnectionPoolSize` limit has been reached, a session will wait this duration for a connection to be made available.
+Since the process of acquiring a connection may involve creating a new connection, *_ensure that the value of this configuration is higher than the configured_* `ConnectionTimeout`.
++
+Setting a low value will allow for transactions to *_fail fast_* when all connections in the pool have been acquired by other transactions.
+Setting a higher value will result in these transactions being queued, increasing the chances of eventually acquiring a connection at the cost of longer time to receive feedback on failure.
+Finding an optimal value may require an element of experimentation, taking into consideration the expected levels of parallelism within your application as well as the `MaxConnectionPoolSize`.
++
+*Default:* 60.0
++
+*Type:* float
 +
 .Configure connection pool
 ======
@@ -357,7 +370,20 @@ include::{python-examples}/test_config_connection_pool_example.py[tags=config-co
 ----
 ======
 
-include::{common-content}/client-applications.adoc[tag=configuration-ConnectionTimeout]
+//include::{common-content}/client-applications.adoc[tag=configuration-ConnectionTimeout]
+link:https://neo4j.com/docs/api/python-driver/{neo4j-version}/api.html#connection-timeout[`ConnectionTimeout`]::
+
+The maximum amount of time in secondsfootnote:[Other drivers may use milliseconds instead of seconds for this configuration.] to wait for a TCP connection to be established.
+Connections are only created when a session requires one unless there is an available connection in the connection pool.
+The driver maintains a pool of open connections which can be loaned to a session when one is available.
+If a connection is not available, then an attempt to create a new connection (provided the `MaxConnectionPoolSize` limit has not been reached) is made with this configuration option, providing the maximum amount of time to wait for the connection to be established.
++
+In environments with high latency and high occurrences of connection timeouts it is recommended to configure a higher value.
+For lower latency environments and quicker feedback on potential network issues configure with a lower value.
++
+*Default:* 30.0
++
+*Type:* float
 +
 .Configure connection timeout
 ======
@@ -392,13 +418,42 @@ include::{python-examples}/test_config_unencrypted_example.py[tags=config-unencr
 ----
 ======
 
-include::{common-content}/client-applications.adoc[tag=configuration-MaxConnectionLifetime]
+//include::{common-content}/client-applications.adoc[tag=configuration-MaxConnectionLifetime]
+link:https://neo4j.com/docs/api/python-driver/{neo4j-version}/api.html#max-connection-lifetime[`MaxConnectionLifetime`]::
+
+The maximum duration in secondsfootnote:[Other drivers may use milliseconds instead of seconds for this configuration.] the driver will keep a connection for before being removed from the pool.
+Note that while the driver will respect this value, it is possible that the network environment will close connections inside this lifetime.
+This is beyond the control of the driver.
+The check on the connection’s lifetime happens when a session requires a connection.
+If the available connection’s lifetime is over this limit it is closed and a new connection is created, added to the pool and returned to the requesting session.
+Changing this configuration value would be useful in environments where users don’t have full control over the network environment and wish to proactively ensure all connections are ready.
++
+Setting this option to a low value will cause a high connection churn rate, and can result in a performance drop.
+It is recommended to pick a value smaller than the maximum lifetime exposed by the surrounding system infrastructure (such as operating system, router, load balancer, proxy and firewall).
+Negative values result in lifetime not being checked.
++
+*Default:* 3600
++
+*Type:* float
 
 include::{common-content}/client-applications.adoc[tag=configuration-MaxConnectionPoolSize]
 +
 *Default:* 100 connections
 
-include::{common-content}/client-applications.adoc[tag=configuration-MaxTransactionRetryTime]
+//include::{common-content}/client-applications.adoc[tag=configuration-MaxTransactionRetryTime]
+link:https://neo4j.com/docs/api/python-driver/{neo4j-version}/api.html#max-transaction-retry-time[`MaxTransactionRetryTime`]::
+
+The maximum amount of time in secondsfootnote:[Other drivers may use milliseconds instead of seconds for this configuration.] that a managed transaction will retry for before failing.
+Queries that are executed within a managed transaction gain the benefit of being retried when a transient error occurs.
+When this happens the transaction is retired multiple times up to the `MaxTransactionRetryTime`.
++
+Configure this option higher in high latency environments or if you are executing many large transactions which could limit the number of times that they are retired and therefore their chance to succeed.
+Configure lower in low latency environments and where your workload mainly consists of many smaller transactions.
+Failing transactions faster may highlight the reasons behind the transient errors making it easier to fix underlying issues.
++
+*Default:* 30.0
++
+*Type:* float
 +
 .Configure maximum retry time
 ======

pythonManual/docbook/content-map.xml

@@ -9,10 +9,6 @@
     <d:tocentry linkend="python-driver-cypher-workflow"><?dbhtml filename="cypher-workflow/index.html"?>
     </d:tocentry>
     <d:tocentry linkend="python-driver-session-api"><?dbhtml filename="session-api/index.html"?>
-      <d:tocentry linkend="python-driver-simple-sessions"><?dbhtml filename="session-api/simple/index.html"?>
-      </d:tocentry>
-      <d:tocentry linkend="python-driver-session-configuration"><?dbhtml filename="session-api/configuration/index.html"?>
-      </d:tocentry>
     </d:tocentry>
     <d:tocentry linkend="python-driver-terminology"><?dbhtml filename="terminology/index.html"?>
     </d:tocentry>