update docs:

- fix typos
- sync changes to md

Author: krylosov-aa

Makefile

@@ -22,3 +22,6 @@ build:
 
 publish:
 	uv publish
+
+build_docs:
+	mkdocs build -f docs_sources/mkdocs.yml -d ../docs

docs/404.html

@@ -45,7 +45,7 @@
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="/examples">Usage Examples</a>
+                <li class="toctree-l1"><a class="reference internal" href="/examples/">Usage Examples</a>
                 </li>
               </ul>
               <ul>

docs/api/index.html

@@ -18,7 +18,7 @@
       </script>
 
     <!--[if lt IE 9]>
-    <script src="../js/html5shiv.min.js"></script>
+      <script src="../js/html5shiv.min.js"></script>
     <![endif]-->
       <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
       <script>hljs.highlightAll();</script> 
@@ -44,15 +44,15 @@
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../problem">The Problem It Solves</a>
+                <li class="toctree-l1"><a class="reference internal" href="../problem/">The Problem It Solves</a>
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../getting_started">Getting Started</a>
+                <li class="toctree-l1"><a class="reference internal" href="../getting_started/">Getting Started</a>
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../examples">Usage Examples</a>
+                <li class="toctree-l1"><a class="reference internal" href="../examples/">Usage Examples</a>
                 </li>
               </ul>
               <ul class="current">
@@ -122,19 +122,19 @@
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../concurrent_queries">Concurrent SQL Queries</a>
+                <li class="toctree-l1"><a class="reference internal" href="../concurrent_queries/">Concurrent SQL Queries</a>
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../master_replica">Master/Replica or several databases at the same time</a>
+                <li class="toctree-l1"><a class="reference internal" href="../master_replica/">Master/Replica or several databases at the same time</a>
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../testing">Testing</a>
+                <li class="toctree-l1"><a class="reference internal" href="../testing/">Testing</a>
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../how_middleware_works">How middleware works</a>
+                <li class="toctree-l1"><a class="reference internal" href="../how_middleware_works/">How middleware works</a>
                 </li>
               </ul>
       </div>
@@ -152,6 +152,9 @@
   <ul class="wy-breadcrumbs">
     <li><a href=".." class="icon icon-home" aria-label="Docs"></a></li>
       <li class="breadcrumb-item active">API Reference</li>
+    <li class="wy-breadcrumbs-aside">
+          <a href="https://github.com/krylosov-aa/context-async-sqlalchemy/edit/master/docs/api.md" class="icon icon-github"> Edit on GitHub</a>
+    </li>
   </ul>
   <hr/>
 </div>
@@ -160,14 +163,13 @@
 
                 <h1 id="api-reference">API Reference</h1>
 <h2 id="dbconnect">DBConnect</h2>
-<p>DBConnect is responsible for managing the engine and <code>session_maker</code>.
-You need to define two factories:
-  <ul>
-    <li>Specify host to which you want to connect (optional).</li>
-    <li>Specify a handler that runs before a session is created. It be used to connect to the host for the first time or
-to reconnect to a new one.</li>
-   </ul>
-</p>
+<p>DBConnect is responsible for managing the engine and <code>session_maker</code>
+You need to define two factories:</p>
+<ul>
+<li>Specify host to which you want to connect (optional).</li>
+<li>Specify a handler that runs before a session is created.
+It will be used to connect to the host for the first time or to reconnect to a new one (optional).</li>
+</ul>
 <h3 id="init">init</h3>
 <pre><code class="language-python">def __init__(
     self: DBConnect,
@@ -211,20 +213,20 @@ <h3 id="connect">connect</h3>
 </code></pre>
 <p>Establishes a connection to the specified host.
 It doesn’t need to be called explicitly.
-The first session request automatically
+If you don't use the call, the first session request will automatically
 establishes the connection.</p>
 <hr />
 <h3 id="change_host">change_host</h3>
 <pre><code class="language-python">async def change_host(self: DBConnect, host: str) -&gt; None:
 </code></pre>
-Establishes a connection to the specified host. It validates that the currently connected host is different
+<p>Establishes a connection to the specified host. It then validates that the currently connected host is different
 from the target host.</p>
 <hr />
 <h3 id="create_session">create_session</h3>
 <pre><code class="language-python">async def create_session(self: DBConnect) -&gt; AsyncSession:
 </code></pre>
 <p>Creates a new session the library uses internally.
-You never need to call it directly.</p>
+You never need to call it directly. (Only maybe in some special cases.)</p>
 <hr />
 <h3 id="session_maker">session_maker</h3>
 <pre><code class="language-python">async def session_maker(self: DBConnect) -&gt; async_sessionmaker[AsyncSession]:
@@ -237,8 +239,8 @@ <h3 id="close">close</h3>
 <p>Closes and cleans up all resources, freeing the connection pool.
 Use this call at the end of your application’s life cycle.</p>
 <h2 id="middlewares">Middlewares</h2>
-<p>Most of the work the “magic” happens inside the middleware. Check out <a href="../how_middleware_works">how it works</a> and implement your
-own.</p>
+<p>Most of the work the “magic” happens inside the middleware. Check out
+<a href="../how_middleware_works/">how it works</a> and implement your own if the ready-made ones don't fit.</p>
 <h3 id="fastapi">FastAPI</h3>
 <pre><code class="language-python">from context_async_sqlalchemy.fastapi_utils import (
     fastapi_http_db_session_middleware,
@@ -290,7 +292,7 @@ <h3 id="db_session">db_session</h3>
 <pre><code class="language-python">async def db_session(connect: DBConnect) -&gt; AsyncSession:
 </code></pre>
 <p>The most important function for obtaining a session in your code.
-When called for the first time, it returns a new session; subsequent
+Returns a new session when you call it for the first time; subsequent
 calls return the same session.</p>
 <hr />
 <h3 id="atomic_db_session">atomic_db_session</h3>
@@ -300,7 +302,7 @@ <h3 id="atomic_db_session">atomic_db_session</h3>
     current_transaction: Literal[&quot;commit&quot;, &quot;rollback&quot;, &quot;append&quot;, &quot;raise&quot;] = &quot;commit&quot;,
 ) -&gt; AsyncGenerator[AsyncSession, None]:
 </code></pre>
-<p>A context manager that can be used to wrap another function which
+<p>A context manager you can use to wrap another function which
 uses a context session, making that call isolated within its own transaction.</p>
 <p>Several options define how a function handles an open transaction.</p>
 <p>current_transaction:</p>
@@ -325,27 +327,29 @@ <h3 id="close_db_session">close_db_session</h3>
 <pre><code class="language-python">async def close_db_session(connect: DBConnect) -&gt; None:
 </code></pre>
 <p>Closes the current context session and returns the connection to the pool.
-If you close an uncommitted transaction, the connection rolls back.</p>
-<p>This is useful if a database querly is needed at the beginning of the handle.</p>
-<p>You have have more work you need to complete over time without being able to keep the connection open.</p>
+If you close an uncommitted transaction, the connection rolls back</p>
+<p>This is useful when you need to run a database query at the start of the
+handler, then continue working over time without keeping the connection open.</p>
 <hr />
 <h3 id="new_non_ctx_session">new_non_ctx_session</h3>
 <pre><code class="language-python">@asynccontextmanager
 async def new_non_ctx_session(
     connect: DBConnect,
 ) -&gt; AsyncGenerator[AsyncSession, None]:
 </code></pre>
-<p>A context manager that allows you to create a new session without placing it in a context.</p>
+<p>A context manager that allows you to create a new session without
+placing it in a context.</p>
 <hr />
 <h3 id="new_non_ctx_atomic_session">new_non_ctx_atomic_session</h3>
 <pre><code class="language-python">@asynccontextmanager
 async def new_non_ctx_atomic_session(
     connect: DBConnect,
 ) -&gt; AsyncGenerator[AsyncSession, None]:
 </code></pre>
-<p>A context manager that allows you to create a new session with
-a new transaction that isn't placed in a context. It's used for manual
-session management when you don't want to use a context.</p>
+<p>Runs a function in a new context with new session(s) that have a separate connection.</p>
+<p>It commits the transaction automatically if <code>callable_func</code> does not
+raise exceptions. Otherwise, the transaction rolls back.</p>
+<p>It is intended to allow you to run multiple database queries concurrently.</p>
 <h2 id="context">Context</h2>
 <h3 id="run_in_new_ctx">run_in_new_ctx</h3>
 <pre><code class="language-python">async def run_in_new_ctx(
@@ -355,9 +359,9 @@ <h3 id="run_in_new_ctx">run_in_new_ctx</h3>
 ) -&gt; AsyncCallableResult:
 </code></pre>
 <p>Runs a function in a new context with new session(s) that have a
-        separate connection.</p>
+separate connection.</p>
 <p>It commits the transaction automatically if <code>callable_func</code> does not
-    raise exceptions. Otherwise, the transaction rolls back.</p>
+raise exceptions. Otherwise, the transaction rolls back.</p>
 <p>It is intended to allow you to run multiple database queries concurrently.</p>
 <p>example of use:</p>
 <pre><code class="language-python">await asyncio.gather(
@@ -369,7 +373,6 @@ <h3 id="run_in_new_ctx">run_in_new_ctx</h3>
 )
 </code></pre>
 <h2 id="testing">Testing</h2>
-
 <h3 id="rollback_session">rollback_session</h3>
 <pre><code class="language-python">@asynccontextmanager
 async def rollback_session(
@@ -388,7 +391,7 @@ <h3 id="set_test_context">set_test_context</h3>
 It is intended to test the application when it shares a single transaction.</p>
 <p>Use <code>auto_close=False</code> if you’re using a test session and transaction
 that you close elsewhere in your code.</p>
-<p>Use <code>auto_close=True</code> to call a function
+<p>Use <code>auto_close=True</code> if you want to call a function
 in a test that uses a context while the middleware is not
 active. All sessions close automatically.</p>
 <hr />
@@ -401,17 +404,15 @@ <h3 id="put_savepoint_session_in_ctx">put_savepoint_session_in_ctx</h3>
 <p>Sets the context to a session that uses a save point instead of creating
         a transaction. You need to pass the session you're using inside
         your tests to attach a new session to the same connection.</p>
-
 <pre><code>It is important to use this function inside set_test_context.
 </code></pre>
-
-<p>Learn more about <a href="../testing">testing</a>.</p>
+<p>Learn more about <a href="../testing/">testing</a></p>
 
             </div>
           </div><footer>
     <div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
-        <a href="../examples" class="btn btn-neutral float-left" title="Usage Examples"><span class="icon icon-circle-arrow-left"></span> Previous</a>
-        <a href="../concurrent_queries" class="btn btn-neutral float-right" title="Concurrent SQL Queries">Next <span class="icon icon-circle-arrow-right"></span></a>
+        <a href="../examples/" class="btn btn-neutral float-left" title="Usage Examples"><span class="icon icon-circle-arrow-left"></span> Previous</a>
+        <a href="../concurrent_queries/" class="btn btn-neutral float-right" title="Concurrent SQL Queries">Next <span class="icon icon-circle-arrow-right"></span></a>
     </div>
 
   <hr/>
@@ -438,10 +439,10 @@ <h3 id="put_savepoint_session_in_ctx">put_savepoint_session_in_ctx</h3>
         </span>
 
 
-      <span><a href="../examples" style="color: #fcfcfc">&laquo; Previous</a></span>
+      <span><a href="../examples/" style="color: #fcfcfc">&laquo; Previous</a></span>
 
 
-      <span><a href="../concurrent_queries" style="color: #fcfcfc">Next &raquo;</a></span>
+      <span><a href="../concurrent_queries/" style="color: #fcfcfc">Next &raquo;</a></span>
 
   </span>
 </div>

docs/concurrent_queries/index.html

@@ -18,7 +18,7 @@
       </script>
 
     <!--[if lt IE 9]>
-    <script src="../js/html5shiv.min.js"></script>
+      <script src="../js/html5shiv.min.js"></script>
     <![endif]-->
       <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
       <script>hljs.highlightAll();</script> 
@@ -44,19 +44,19 @@
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../problem">The Problem It Solves</a>
+                <li class="toctree-l1"><a class="reference internal" href="../problem/">The Problem It Solves</a>
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../getting_started">Getting Started</a>
+                <li class="toctree-l1"><a class="reference internal" href="../getting_started/">Getting Started</a>
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../examples">Usage Examples</a>
+                <li class="toctree-l1"><a class="reference internal" href="../examples/">Usage Examples</a>
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../api">API Reference</a>
+                <li class="toctree-l1"><a class="reference internal" href="../api/">API Reference</a>
                 </li>
               </ul>
               <ul class="current">
@@ -66,15 +66,15 @@
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../master_replica">Master/Replica or several databases at the same time</a>
+                <li class="toctree-l1"><a class="reference internal" href="../master_replica/">Master/Replica or several databases at the same time</a>
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../testing">Testing</a>
+                <li class="toctree-l1"><a class="reference internal" href="../testing/">Testing</a>
                 </li>
               </ul>
               <ul>
-                <li class="toctree-l1"><a class="reference internal" href="../how_middleware_works">How middleware works</a>
+                <li class="toctree-l1"><a class="reference internal" href="../how_middleware_works/">How middleware works</a>
                 </li>
               </ul>
       </div>
@@ -92,6 +92,9 @@
   <ul class="wy-breadcrumbs">
     <li><a href=".." class="icon icon-home" aria-label="Docs"></a></li>
       <li class="breadcrumb-item active">Concurrent SQL Queries</li>
+    <li class="wy-breadcrumbs-aside">
+          <a href="https://github.com/krylosov-aa/context-async-sqlalchemy/edit/master/docs/concurrent_queries.md" class="icon icon-github"> Edit on GitHub</a>
+    </li>
   </ul>
   <hr/>
 </div>
@@ -126,10 +129,10 @@ <h1 id="concurrent-sql-queries">Concurrent sql queries</h1>
 
 async def handler_multiple_sessions() -&gt; None:
     &quot;&quot;&quot;
-    You may need to to run multiple sessions. For example, to run several queries concurrently.
+    You may need to run multiple sessions. For example, to run several queries concurrently.
 
     You can also use the same techniques to create new sessions whenever you
-        need them, ot necessarily because of the concurrent processing.
+        need them, not necessarily because of the concurrent processing.
     &quot;&quot;&quot;
     await asyncio.gather(
         _insert(),  # context session
@@ -182,8 +185,8 @@ <h1 id="concurrent-sql-queries">Concurrent sql queries</h1>
             </div>
           </div><footer>
     <div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
-        <a href="../api" class="btn btn-neutral float-left" title="API Reference"><span class="icon icon-circle-arrow-left"></span> Previous</a>
-        <a href="../master_replica" class="btn btn-neutral float-right" title="Master/Replica or several databases at the same time">Next <span class="icon icon-circle-arrow-right"></span></a>
+        <a href="../api/" class="btn btn-neutral float-left" title="API Reference"><span class="icon icon-circle-arrow-left"></span> Previous</a>
+        <a href="../master_replica/" class="btn btn-neutral float-right" title="Master/Replica or several databases at the same time">Next <span class="icon icon-circle-arrow-right"></span></a>
     </div>
 
   <hr/>
@@ -210,10 +213,10 @@ <h1 id="concurrent-sql-queries">Concurrent sql queries</h1>
         </span>
 
 
-      <span><a href="../api" style="color: #fcfcfc">&laquo; Previous</a></span>
+      <span><a href="../api/" style="color: #fcfcfc">&laquo; Previous</a></span>
 
 
-      <span><a href="../master_replica" style="color: #fcfcfc">Next &raquo;</a></span>
+      <span><a href="../master_replica/" style="color: #fcfcfc">Next &raquo;</a></span>
 
   </span>
 </div>