Improve CSS style for the documentation

Author: Cito

dbutils/steady_db.py

@@ -651,6 +651,8 @@ def tough_method(*args, **kwargs):
                             if execute:
                                 self._setsizes(cursor2)
                             method2 = getattr(cursor2, name)
+                            # if the following call hangs,
+                            # you may have forgotten to call begin()
                             result = method2(*args, **kwargs)
                             if execute:
                                 self._clearsizes()

docs/doc.css

@@ -1,39 +1,13 @@
 /*
-	Webware for Python (https://webwareforpython.github.io/w4py/)
-
-	Common style sheet for Webware's documentation pages
+	Style sheet for DBUtils documentation pages.
 */
 
 /* First import default style for pages created with Docutils: */
 
 @import url(docutils.css);
 
-/* Customization for Webware goes here: */
+/* Customization for DBUtils goes here: */
 
-body {
-	background-color: #FFFFFF;
-	font-family: Verdana, Arial, Helvetica, sans-serif;
-	font-size: 10pt;
-	padding: 12pt;
-}
-table {
-	empty-cells: show;
-	border-collapse: collapse;
-	margin: 0 auto;
-}
-table.doc {
-	border-spacing: 2px;
-	border-collapse: separate;
-	border-style: none;
-}
-td, th {
-	font-family: Verdana, Arial, Helvetica, sans-serif;
-	font-size: 10pt;
-}
-table.doc td, table.doc th {
-	padding: 4px;
-	border-style: none;
-}
 p {
 	margin-top: 6pt;
 	margin-bottom: 6pt;
@@ -43,11 +17,9 @@ li {
 	margin-bottom: 6pt;
 }
 h1, h2 {
-	font-family: Verdana, Arial, Helvetica, sans-serif;
 	color: #002352;
 }
 h3, h4 {
-	font-family: Verdana, Arial, Helvetica, sans-serif;
 	color: #002352;
 }
 h1 {
@@ -59,119 +31,45 @@ h2 {
 h3 {
 	font-size: 14pt;
 }
-h4 {
-	font-size: 12pt;
-}
-h5 {
-	font-size: 11pt;
-}
-h6 {
-	font-size: 10pt;
-}
-h1.titlebar {
-	padding: 4pt;
-	margin-bottom: 12pt;
-	text-align: center;
-	color: white;
-	background-color: #025;
-}
-h1.title, h1.header {
+h1.title {
 	padding: 4pt;
 	margin-bottom: 12pt;
 	text-align: center;
 	border-bottom: 1pt solid #025;
 	padding-bottom: 8pt;
 }
-div.footer {
-	font-family: Tahoma, Arial, Helvetica, sans-serif;
-	font-size: 9pt;
-	text-align: center;
-	padding: 4pt;
-	margin-top: 16pt;
-	border-top: 1pt solid #025;
-}
-.left {
-	text-align: left;
-}
-.right {
-	text-align: right;
-}
-.center {
-	text-align: center;
-}
-.top {
-	vertical-align: top;
-}
-.nowrap {
-	white-space: nowrap;
-}
-.contents {
-	font-family: Tahoma, Arial, Helvetica, sans-serif;
-}
 .contents ul {
 	list-style: none;
 	margin-bottom: 24pt;
 	padding-left: 0em;
 	margin-left: 2em;
 }
 .contents ul li {
-	font-size: 11pt;
-	margin-bottom: 3pt;
+	font-size: 14pt;
+	margin-bottom: 2pt;
 }
 .contents ul ul {
 	list-style-type: none;
-	margin-top: 2pt;
-	margin-bottom: 2pt;
+	margin-top: 1pt;
+	margin-bottom: 1pt;
 	padding-left: 0em;
 	margin-left: 1.5em;
 }
 .contents ul ul li {
-	font-size: 10pt;
+	font-size: 13pt;
 	margin-bottom: 1pt;
 }
-.contents .topic-title {
-	font-size: 16pt;
-}
-span.name {
-	font-weight: bold;
-}
-span.filename {
-	font-family: Tahoma, Arial, Helvetica, sans-serif;
-	font-size: 9pt;
-}
-code, .literal, .literal-block, .pre, .py {
-	font-family: "Andale Mono", "Lucida Console", Monaco, "Courier New", Courier, monospace;
-	font-size: 10pt;
-	color: #052;
-}
-tt.literal, span.pre {
-	background-color: #FFFFFF;
-}
-pre.py, pre.literal-block {
-	margin: 0;
-	padding: 2pt 1pt 1pt 2pt;
-	background-color: #F0F0F8;
-}
-.typed {
-	font-weight: bold;
-}
-.error {
-	color: red;
+.contents > p.topic-title {
+	font-size: 24pt;
 }
 .warning {
 	color: brown;
 }
-
-/* Configuration documentation: */
-
-dl.config {
-}
-dt.config {
-}
-dd.config {
+.admonition-title {
+	background-color: #F5F5DC;
+	padding: 1pt 3pt;
 }
-span.setting {
-	font-family: Tahoma, Arial, Helvetica, sans-serif;
-	font-size: 9pt;
-	font-weight: bold;
+.admonition-title::before {
+    content: "⚠";
+    margin-right: .5em;
 }

docs/docutils.css

@@ -321,11 +321,14 @@ <h3>PersistentDB (persistent_db)</h3>
 Stattdessen wird die Verbindung automatisch dann geschlossen, wenn der Thread
 endet. Sie können dieses Verhalten ändern, indem Sie den Parameter namens
 <span class="docutils literal">closeable</span> setzen.</p>
+<aside class="admonition warning">
+<p class="admonition-title">Warnung</p>
 <p>Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
 <span class="docutils literal">begin()</span> eingeleitet werden müssen. Hierdurch wird sichergestellt, dass
 das transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
 ausgesetzt wird, und dass die Verbindung zurückgerollt wird, before sie vom
 gleichen Thread erneut benutzt wird.</p>
+</aside>
 <p>Das Holen einer Verbindung kann etwas beschleunigt werden, indem man den
 Parameter <span class="docutils literal">threadlocal</span> auf <span class="docutils literal">threading.local</span> setzt; dies könnte aber in
 einigen Umgebungen nicht funktionieren (es ist zum Beispiel bekannt, dass
@@ -428,12 +431,15 @@ <h3>PooledDB (pooled_db)</h3>
     with db.cursor() as cur:
         cur.execute(...)
         res = cur.fetchone()</pre>
+<aside class="admonition warning">
+<p class="admonition-title">Warnung</p>
 <p>Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
 <span class="docutils literal">begin()</span> eingeleitet werden müssen. Hierdurch wird sichergestellt,
 dass die Verbindung nicht mehr mit anderen Threads geteilt wird, dass das
 transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
 ausgesetzt wird, und dass die Verbindung zurückgerollt wird, bevor sie
 wieder an den Verbindungspool zurückgegeben wird.</p>
+</aside>
 </section>
 </section>
 <section id="besonderheiten-bei-der-benutzung">

docs/main.de.html

@@ -317,11 +317,12 @@ Stattdessen wird die Verbindung automatisch dann geschlossen, wenn der Thread
 endet. Sie können dieses Verhalten ändern, indem Sie den Parameter namens
 ``closeable`` setzen.
 
-Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
-``begin()`` eingeleitet werden müssen. Hierdurch wird sichergestellt, dass
-das transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
-ausgesetzt wird, und dass die Verbindung zurückgerollt wird, before sie vom
-gleichen Thread erneut benutzt wird.
+.. warning::
+    Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
+    ``begin()`` eingeleitet werden müssen. Hierdurch wird sichergestellt, dass
+    das transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
+    ausgesetzt wird, und dass die Verbindung zurückgerollt wird, before sie vom
+    gleichen Thread erneut benutzt wird.
 
 Das Holen einer Verbindung kann etwas beschleunigt werden, indem man den
 Parameter ``threadlocal`` auf ``threading.local`` setzt; dies könnte aber in
@@ -452,13 +453,13 @@ Sie können dies auch durch Verwendung von Kontext-Managern vereinfachen::
           cur.execute(...)
           res = cur.fetchone()
 
-
-Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
-``begin()`` eingeleitet werden müssen. Hierdurch wird sichergestellt,
-dass die Verbindung nicht mehr mit anderen Threads geteilt wird, dass das
-transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
-ausgesetzt wird, und dass die Verbindung zurückgerollt wird, bevor sie
-wieder an den Verbindungspool zurückgegeben wird.
+.. warning::
+    Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
+    ``begin()`` eingeleitet werden müssen. Hierdurch wird sichergestellt,
+    dass die Verbindung nicht mehr mit anderen Threads geteilt wird, dass das
+    transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
+    ausgesetzt wird, und dass die Verbindung zurückgerollt wird, bevor sie
+    wieder an den Verbindungspool zurückgegeben wird.
 
 
 Besonderheiten bei der Benutzung

docs/main.de.rst

@@ -298,10 +298,13 @@ <h3>PersistentDB (persistent_db)</h3>
 contrary to the intent of having persistent connections. Instead,
 the connection will be automatically closed when the thread dies.
 You can change this behavior by setting the <span class="docutils literal">closeable</span> parameter.</p>
+<aside class="admonition warning">
+<p class="admonition-title">Warning</p>
 <p>Note that you need to explicitly start transactions by calling the
 <span class="docutils literal">begin()</span> method. This ensures that the transparent reopening will be
 suspended until the end of the transaction, and that the connection
 will be rolled back before being reused by the same thread.</p>
+</aside>
 <p>By setting the <span class="docutils literal">threadlocal</span> parameter to <span class="docutils literal">threading.local</span>, getting
 connections may become a bit faster, but this may not work in all
 environments (for instance, <span class="docutils literal">mod_wsgi</span> is known to cause problems
@@ -374,7 +377,7 @@ <h3>PooledDB (pooled_db)</h3>
 <pre class="literal-block">db = pool.dedicated_connection()</pre>
 <p>If you don't need it anymore, you should immediately return it to the
 pool with <span class="docutils literal">db.close()</span>. You can get another connection in the same way.</p>
-<p><em>Warning:</em> In a threaded environment, never do the following:</p>
+<p>⚠ Warning: In a threaded environment, never do the following:</p>
 <pre class="literal-block">pool.connection().cursor().execute(...)</pre>
 <p>This would release the connection too early for reuse which may be fatal
 if the connections are not thread-safe. Make sure that the connection
@@ -390,11 +393,14 @@ <h3>PooledDB (pooled_db)</h3>
     with db.cursor() as cur:
         cur.execute(...)
         res = cur.fetchone()</pre>
+<aside class="admonition warning">
+<p class="admonition-title">Warning</p>
 <p>Note that you need to explicitly start transactions by calling the
 <span class="docutils literal">begin()</span> method. This ensures that the connection will not be shared
 with other threads, that the transparent reopening will be suspended
 until the end of the transaction, and that the connection will be rolled
 back before being given back to the connection pool.</p>
+</aside>
 </section>
 </section>
 <section id="advanced-usage">