From 13d495fc869741072dc5dc685518ef35f6dacd62 Mon Sep 17 00:00:00 2001 From: Cycloctane Date: Tue, 1 Oct 2024 02:03:02 +0800 Subject: [PATCH 1/7] replace blockdiag with graphviz in docs --- docs/conf.py | 2 +- docs/tracing_reference.rst | 140 +++++++++++++++++++++++--------- requirements/broken-projects.in | 1 - requirements/constraints.txt | 18 +--- requirements/dev.txt | 18 +--- requirements/doc-spelling.txt | 23 +----- requirements/doc.in | 1 - requirements/doc.txt | 17 +--- 8 files changed, 108 insertions(+), 112 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index af988c9acb4..f716c35ffca 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,8 +56,8 @@ "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinx.ext.viewcode", + "sphinx.ext.graphviz", # 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 index cf7264d8955..3ec52e16d0c 100644 --- 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 index 02d95f8b948..e69de29bb2d 100644 --- a/requirements/broken-projects.in +++ b/requirements/broken-projects.in @@ -1 +0,0 @@ -Pillow < 10 # https://github.com/blockdiag/sphinxcontrib-blockdiag/issues/26 diff --git a/requirements/constraints.txt b/requirements/constraints.txt index 63c533048b2..cca43fe5cbf 100644 --- a/requirements/constraints.txt +++ b/requirements/constraints.txt @@ -24,8 +24,6 @@ async-timeout==4.0.3 ; python_version < "3.11" # valkey 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 @@ -76,8 +74,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 @@ -130,10 +126,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 @@ -161,9 +153,7 @@ pygments==2.18.0 # rich # sphinx pyjwt==2.8.0 - # via - # gidgethub - # pyjwt + # via gidgethub pyproject-hooks==1.2.0 # via # build @@ -210,13 +200,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 @@ -278,8 +265,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 @@ -294,6 +279,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 index 710cff8e2bb..719138b0f97 100644 --- a/requirements/dev.txt +++ b/requirements/dev.txt @@ -24,8 +24,6 @@ async-timeout==4.0.3 ; python_version < "3.11" # valkey 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 @@ -74,8 +72,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 @@ -127,10 +123,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 @@ -156,9 +148,7 @@ pygments==2.18.0 # rich # sphinx pyjwt==2.8.0 - # via - # gidgethub - # pyjwt + # via gidgethub pyproject-hooks==1.2.0 # via # build @@ -205,12 +195,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 @@ -270,8 +257,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 @@ -286,6 +271,5 @@ pip==24.2 # via pip-tools setuptools==75.1.0 # via - # blockdiag # incremental # pip-tools diff --git a/requirements/doc-spelling.txt b/requirements/doc-spelling.txt index 54fc21c538e..2877dee8f5f 100644 --- a/requirements/doc-spelling.txt +++ b/requirements/doc-spelling.txt @@ -1,8 +1,8 @@ # -# This file is autogenerated by pip-compile with python 3.8 -# To update, run: +# This file is autogenerated by pip-compile with Python 3.8 +# by the following command: # -# pip-compile --allow-unsafe --output-file=requirements/doc-spelling.txt --resolver=backtracking --strip-extras requirements/doc-spelling.in +# pip-compile --allow-unsafe --output-file=requirements/doc-spelling.txt --strip-extras requirements/doc-spelling.in # aiohttp-theme==0.1.7 # via -r requirements/doc.in @@ -10,8 +10,6 @@ alabaster==0.7.13 # via sphinx babel==2.16.0 # via sphinx -blockdiag==3.0.0 - # via sphinxcontrib-blockdiag certifi==2024.8.30 # via requests charset-normalizer==3.3.2 @@ -20,8 +18,6 @@ click==8.1.7 # via towncrier docutils==0.20.1 # via sphinx -funcparserlib==1.0.1 - # via blockdiag idna==3.6 # via requests imagesize==1.4.1 @@ -40,10 +36,6 @@ markupsafe==2.1.5 # via jinja2 packaging==24.1 # via sphinx -pillow==9.5.0 - # via - # -c requirements/broken-projects.in - # blockdiag pyenchant==3.2.2 # via sphinxcontrib-spelling pygments==2.18.0 @@ -57,13 +49,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 @@ -88,8 +77,6 @@ towncrier==23.11.0 # sphinxcontrib-towncrier urllib3==2.2.3 # via requests -webcolors==24.8.0 - # via blockdiag zipp==3.20.2 # via # importlib-metadata @@ -97,6 +84,4 @@ zipp==3.20.2 # The following packages are considered to be unsafe in a requirements file: setuptools==75.1.0 - # via - # blockdiag - # incremental + # via incremental diff --git a/requirements/doc.in b/requirements/doc.in index 1e0b6568724..550a6eeec47 100644 --- a/requirements/doc.in +++ b/requirements/doc.in @@ -2,6 +2,5 @@ aiohttp-theme sphinx -sphinxcontrib-blockdiag sphinxcontrib-towncrier towncrier diff --git a/requirements/doc.txt b/requirements/doc.txt index 08c896b2a51..e5c50286224 100644 --- a/requirements/doc.txt +++ b/requirements/doc.txt @@ -10,8 +10,6 @@ alabaster==0.7.13 # via sphinx babel==2.16.0 # via sphinx -blockdiag==3.0.0 - # via sphinxcontrib-blockdiag certifi==2024.8.30 # via requests charset-normalizer==3.3.2 @@ -20,8 +18,6 @@ click==8.1.7 # via towncrier docutils==0.20.1 # via sphinx -funcparserlib==1.0.1 - # via blockdiag idna==3.6 # via requests imagesize==1.4.1 @@ -40,10 +36,6 @@ markupsafe==2.1.5 # via jinja2 packaging==24.1 # via sphinx -pillow==9.5.0 - # via - # -c requirements/broken-projects.in - # blockdiag pygments==2.18.0 # via sphinx pytz==2024.2 @@ -55,12 +47,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 @@ -83,8 +72,6 @@ towncrier==23.11.0 # sphinxcontrib-towncrier urllib3==2.2.3 # via requests -webcolors==24.8.0 - # via blockdiag zipp==3.20.2 # via # importlib-metadata @@ -92,6 +79,4 @@ zipp==3.20.2 # The following packages are considered to be unsafe in a requirements file: setuptools==75.1.0 - # via - # blockdiag - # incremental + # via incremental From de8c1e742a046963e2567952248b49e7fbbf7ea5 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 30 Sep 2024 18:10:14 +0000 Subject: [PATCH 2/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/tracing_reference.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tracing_reference.rst b/docs/tracing_reference.rst index 3ec52e16d0c..a5e89f24188 100644 --- a/docs/tracing_reference.rst +++ b/docs/tracing_reference.rst @@ -118,9 +118,9 @@ Connection acquiring * - Name - Description * - begin - - + - * - end - - + - * - queued_start - on_connection_queued_start * - create_start @@ -167,9 +167,9 @@ DNS resolving * - Name - Description * - begin - - + - * - end - - + - * - exception - Exception raised * - resolve_end From 78ffdded93522fcc5f1016ed61cb8e8045d5669d Mon Sep 17 00:00:00 2001 From: Cycloctane Date: Tue, 1 Oct 2024 03:04:36 +0800 Subject: [PATCH 3/7] update 9359.contrib.rst --- CHANGES/9359.contrib.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 CHANGES/9359.contrib.rst diff --git a/CHANGES/9359.contrib.rst b/CHANGES/9359.contrib.rst new file mode 100644 index 00000000000..7126377a010 --- /dev/null +++ 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 (conf.py). From 6314d6305249ef0fb04d4c144a51ad33b509455a Mon Sep 17 00:00:00 2001 From: Cycloctane Date: Tue, 1 Oct 2024 11:38:00 +0800 Subject: [PATCH 4/7] delete broken-projects.in --- requirements/broken-projects.in | 0 requirements/doc.in | 2 -- requirements/test.in | 1 - 3 files changed, 3 deletions(-) delete mode 100644 requirements/broken-projects.in diff --git a/requirements/broken-projects.in b/requirements/broken-projects.in deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/requirements/doc.in b/requirements/doc.in index 550a6eeec47..15017b083d3 100644 --- a/requirements/doc.in +++ b/requirements/doc.in @@ -1,5 +1,3 @@ --c broken-projects.in - aiohttp-theme sphinx sphinxcontrib-towncrier diff --git a/requirements/test.in b/requirements/test.in index aca8bce57e2..18423f3743c 100644 --- a/requirements/test.in +++ b/requirements/test.in @@ -1,4 +1,3 @@ --c broken-projects.in -r base.in coverage From 349c02d5a5f8c14fd2b6ff06c278562d74cdd0aa Mon Sep 17 00:00:00 2001 From: Cycloctane Date: Tue, 1 Oct 2024 11:38:22 +0800 Subject: [PATCH 5/7] format --- CHANGES/9359.contrib.rst | 4 ++-- docs/conf.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGES/9359.contrib.rst b/CHANGES/9359.contrib.rst index 7126377a010..cff763e8b09 100644 --- a/CHANGES/9359.contrib.rst +++ b/CHANGES/9359.contrib.rst @@ -1,2 +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 (conf.py). +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 index f716c35ffca..c8b41edda44 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,9 +54,9 @@ extensions = [ # stdlib-party extensions: "sphinx.ext.extlinks", + "sphinx.ext.graphviz", "sphinx.ext.intersphinx", "sphinx.ext.viewcode", - "sphinx.ext.graphviz", # Third-party extensions: "sphinxcontrib.towncrier.ext", # provides `towncrier-draft-entries` directive ] From c8291d5d56820563f88c076b996a5639ebc42e98 Mon Sep 17 00:00:00 2001 From: Cycloctane Date: Tue, 1 Oct 2024 11:55:14 +0800 Subject: [PATCH 6/7] add graphviz installation to readthedocs build process --- .readthedocs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index 1b66ee7c0e4..573abed2129 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -16,6 +16,8 @@ build: python: "3.11" jobs: + post_system_dependencies: + - apt update && apt install -y graphviz post_create_environment: - >- pip install From 7615b508bb300ff8529c22e65a385d37aceb3d28 Mon Sep 17 00:00:00 2001 From: Cycloctane Date: Tue, 1 Oct 2024 12:00:34 +0800 Subject: [PATCH 7/7] fix graphviz installation --- .readthedocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 573abed2129..b3edaf4b8ea 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -14,10 +14,10 @@ build: os: ubuntu-24.04 tools: python: "3.11" + apt_packages: + - graphviz jobs: - post_system_dependencies: - - apt update && apt install -y graphviz post_create_environment: - >- pip install