Backport from PR aio-libs#9359

(replace blockdiag with graphviz in docs)
Cycloctane · Oct 1, 2024 · 60963ef · 60963ef
1 parent dc080fd
commit 60963ef
Show file tree

Hide file tree

Showing 11 changed files with 114 additions and 117 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -14,6 +14,8 @@ build:
   os: ubuntu-24.04
   tools:
     python: "3.11"
+  apt_packages:
+    - graphviz
 
   jobs:
     post_create_environment:

diff --git a/CHANGES/9359.contrib.rst b/CHANGES/9359.contrib.rst
@@ -0,0 +1,2 @@
+Changed diagram images generator from ``blockdiag`` to ``GraphViz``.
+Generating documentation now requires the GraphViz executable to be included in $PATH or sphinx build configuration.
diff --git a/docs/conf.py b/docs/conf.py
@@ -55,10 +55,10 @@
 extensions = [
     # stdlib-party extensions:
     "sphinx.ext.extlinks",
+    "sphinx.ext.graphviz",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     # Third-party extensions:
-    "sphinxcontrib.blockdiag",
     "sphinxcontrib.towncrier.ext",  # provides `towncrier-draft-entries` directive
 ]
 

diff --git a/docs/tracing_reference.rst b/docs/tracing_reference.rst
@@ -21,23 +21,20 @@ A request goes through the following stages and corresponding fallbacks.
 Overview
 ^^^^^^^^
 
-.. blockdiag::
-   :desctable:
+.. graphviz::
 
+   digraph {
 
-   blockdiag {
-     orientation = portrait;
+     start[shape=point, xlabel="start", width="0.1"];
+     redirect[shape=box];
+     end[shape=point, xlabel="end  ", width="0.1"];
+     exception[shape=oval];
 
-     start[shape=beginpoint, description="on_request_start"];
-     redirect[description="on_request_redirect"];
-     end[shape=endpoint, description="on_request_end"];
-     exception[shape=flowchart.terminator, description="on_request_exception"];
-
-     acquire_connection[description="Connection acquiring"];
-     headers_received;
-     headers_sent[description="on_request_headers_sent"];
-     chunk_sent[description="on_request_chunk_sent"];
-     chunk_received[description="on_response_chunk_received"];
+     acquire_connection[shape=box];
+     headers_received[shape=box];
+     headers_sent[shape=box];
+     chunk_sent[shape=box];
+     chunk_received[shape=box];
 
      start -> acquire_connection;
      acquire_connection -> headers_sent;
@@ -57,28 +54,48 @@ Overview
 
    }
 
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Description
+   * - start
+     - on_request_start
+   * - redirect
+     - on_request_redirect
+   * - acquire_connection
+     - Connection acquiring
+   * - headers_received
+     -
+   * - exception
+     - on_request_exception
+   * - end
+     - on_request_end
+   * - headers_sent
+     - on_request_headers_sent
+   * - chunk_sent
+     - on_request_chunk_sent
+   * - chunk_received
+     - on_response_chunk_received
 
 Connection acquiring
 ^^^^^^^^^^^^^^^^^^^^
 
-.. blockdiag::
-   :desctable:
-
-   blockdiag {
-     orientation = portrait;
+.. graphviz::
 
-     begin[shape=beginpoint];
-     end[shape=endpoint];
-     exception[shape=flowchart.terminator, description="Exception raised"];
+   digraph {
 
-     queued_start[description="on_connection_queued_start"];
-     queued_end[description="on_connection_queued_end"];
-     create_start[description="on_connection_create_start"];
-     create_end[description="on_connection_create_end"];
-     reuseconn[description="on_connection_reuseconn"];
+     begin[shape=point, xlabel="begin", width="0.1"];
+     end[shape=point, xlabel="end ", width="0.1"];
+     exception[shape=oval];
 
-     resolve_dns[description="DNS resolving"];
-     sock_connect[description="Connection establishment"];
+     queued_start[shape=box];
+     queued_end[shape=box];
+     create_start[shape=box];
+     create_end[shape=box];
+     reuseconn[shape=box];
+     resolve_dns[shape=box];
+     sock_connect[shape=box];
 
      begin -> reuseconn;
      begin -> create_start;
@@ -95,23 +112,47 @@ Connection acquiring
 
    }
 
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Description
+   * - begin
+     -
+   * - end
+     -
+   * - queued_start
+     - on_connection_queued_start
+   * - create_start
+     - on_connection_create_start
+   * - reuseconn
+     - on_connection_reuseconn
+   * - queued_end
+     - on_connection_queued_end
+   * - create_end
+     - on_connection_create_end
+   * - exception
+     - Exception raised
+   * - resolve_dns
+     - DNS resolving
+   * - sock_connect
+     - Connection establishment
+
 DNS resolving
 ^^^^^^^^^^^^^
 
-.. blockdiag::
-   :desctable:
+.. graphviz::
 
-   blockdiag {
-     orientation = portrait;
+   digraph {
 
-     begin[shape=beginpoint];
-     end[shape=endpoint];
-     exception[shape=flowchart.terminator, description="Exception raised"];
+     begin[shape=point, xlabel="begin", width="0.1"];
+     end[shape=point, xlabel="end", width="0.1"];
+     exception[shape=oval];
 
-     resolve_start[description="on_dns_resolvehost_start"];
-     resolve_end[description="on_dns_resolvehost_end"];
-     cache_hit[description="on_dns_cache_hit"];
-     cache_miss[description="on_dns_cache_miss"];
+     resolve_start[shape=box];
+     resolve_end[shape=box];
+     cache_hit[shape=box];
+     cache_miss[shape=box];
 
      begin -> cache_hit -> end;
      begin -> cache_miss -> resolve_start;
@@ -120,6 +161,25 @@ DNS resolving
 
    }
 
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Description
+   * - begin
+     -
+   * - end
+     -
+   * - exception
+     - Exception raised
+   * - resolve_end
+     - on_dns_resolvehost_end
+   * - resolve_start
+     - on_dns_resolvehost_start
+   * - cache_hit
+     - on_dns_cache_hit
+   * - cache_miss
+     - on_dns_cache_miss
 
 Classes
 -------

diff --git a/requirements/broken-projects.in b/requirements/broken-projects.in
diff --git a/requirements/constraints.txt b/requirements/constraints.txt
@@ -28,8 +28,6 @@ attrs==24.2.0
     # via -r requirements/runtime-deps.in
 babel==2.16.0
     # via sphinx
-blockdiag==3.0.0
-    # via sphinxcontrib-blockdiag
 brotli==1.1.0 ; platform_python_implementation == "CPython"
     # via -r requirements/runtime-deps.in
 build==1.2.2
@@ -80,8 +78,6 @@ frozenlist==1.4.1
     # via
     #   -r requirements/runtime-deps.in
     #   aiosignal
-funcparserlib==1.0.1
-    # via blockdiag
 gidgethub==5.3.0
     # via cherry-picker
 gunicorn==23.0.0
@@ -134,10 +130,6 @@ packaging==24.1
     #   gunicorn
     #   pytest
     #   sphinx
-pillow==9.5.0
-    # via
-    #   -c requirements/broken-projects.in
-    #   blockdiag
 pip-tools==7.4.1
     # via -r requirements/dev.in
 platformdirs==4.3.6
@@ -163,9 +155,7 @@ pygments==2.18.0
     #   rich
     #   sphinx
 pyjwt==2.9.0
-    # via
-    #   gidgethub
-    #   pyjwt
+    # via gidgethub
 pyproject-hooks==1.2.0
     # via
     #   build
@@ -216,13 +206,10 @@ snowballstemmer==2.2.0
 sphinx==7.1.2
     # via
     #   -r requirements/doc.in
-    #   sphinxcontrib-blockdiag
     #   sphinxcontrib-spelling
     #   sphinxcontrib-towncrier
 sphinxcontrib-applehelp==1.0.4
     # via sphinx
-sphinxcontrib-blockdiag==3.0.0
-    # via -r requirements/doc.in
 sphinxcontrib-devhelp==1.0.2
     # via sphinx
 sphinxcontrib-htmlhelp==2.0.1
@@ -283,8 +270,6 @@ virtualenv==20.26.6
     # via pre-commit
 wait-for-it==2.2.2
     # via -r requirements/test.in
-webcolors==24.8.0
-    # via blockdiag
 wheel==0.44.0
     # via pip-tools
 yarl==1.13.1
@@ -299,6 +284,5 @@ pip==24.2
     # via pip-tools
 setuptools==75.1.0
     # via
-    #   blockdiag
     #   incremental
     #   pip-tools
diff --git a/requirements/dev.txt b/requirements/dev.txt
@@ -28,8 +28,6 @@ attrs==24.2.0
     # via -r requirements/runtime-deps.in
 babel==2.16.0
     # via sphinx
-blockdiag==3.0.0
-    # via sphinxcontrib-blockdiag
 brotli==1.1.0 ; platform_python_implementation == "CPython"
     # via -r requirements/runtime-deps.in
 build==1.2.2
@@ -78,8 +76,6 @@ frozenlist==1.4.1
     # via
     #   -r requirements/runtime-deps.in
     #   aiosignal
-funcparserlib==1.0.1
-    # via blockdiag
 gidgethub==5.3.0
     # via cherry-picker
 gunicorn==23.0.0
@@ -131,10 +127,6 @@ packaging==24.1
     #   gunicorn
     #   pytest
     #   sphinx
-pillow==9.5.0
-    # via
-    #   -c requirements/broken-projects.in
-    #   blockdiag
 pip-tools==7.4.1
     # via -r requirements/dev.in
 platformdirs==4.3.6
@@ -158,9 +150,7 @@ pygments==2.18.0
     #   rich
     #   sphinx
 pyjwt==2.8.0
-    # via
-    #   gidgethub
-    #   pyjwt
+    # via gidgethub
 pyproject-hooks==1.2.0
     # via
     #   build
@@ -211,12 +201,9 @@ snowballstemmer==2.2.0
 sphinx==7.1.2
     # via
     #   -r requirements/doc.in
-    #   sphinxcontrib-blockdiag
     #   sphinxcontrib-towncrier
 sphinxcontrib-applehelp==1.0.4
     # via sphinx
-sphinxcontrib-blockdiag==3.0.0
-    # via -r requirements/doc.in
 sphinxcontrib-devhelp==1.0.2
     # via sphinx
 sphinxcontrib-htmlhelp==2.0.1
@@ -275,8 +262,6 @@ virtualenv==20.26.6
     # via pre-commit
 wait-for-it==2.2.2
     # via -r requirements/test.in
-webcolors==24.8.0
-    # via blockdiag
 wheel==0.44.0
     # via pip-tools
 yarl==1.13.1
@@ -291,6 +276,5 @@ pip==24.2
     # via pip-tools
 setuptools==75.1.0
     # via
-    #   blockdiag
     #   incremental
     #   pip-tools
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Changed diagram images generator from ``blockdiag`` to ``GraphViz``.
		Generating documentation now requires the GraphViz executable to be included in $PATH or sphinx build configuration.