diff --git a/.readthedocs.yml b/.readthedocs.yml index 1b66ee7c0e4..b3edaf4b8ea 100644 --- 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 new file mode 100644 index 00000000000..cff763e8b09 --- /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. diff --git a/docs/conf.py b/docs/conf.py index 23ac3e426ec..5cbf398e6a9 100644 --- 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 index 91fc31c33b9..5c60eba9c5c 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 deleted file mode 100644 index 02d95f8b948..00000000000 --- a/requirements/broken-projects.in +++ /dev/null @@ -1 +0,0 @@ -Pillow < 10 # https://github.com/blockdiag/sphinxcontrib-blockdiag/issues/26 diff --git a/requirements/constraints.txt b/requirements/constraints.txt index ab86471e38c..eee37c04f4b 100644 --- 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 index 8e9c0f98d43..49c9142aaf6 100644 --- 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 diff --git a/requirements/doc-spelling.txt b/requirements/doc-spelling.txt index fae36c2f105..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,9 +18,7 @@ click==8.1.7 # via towncrier docutils==0.20.1 # via sphinx -funcparserlib==1.0.1 - # via blockdiag -idna==3.4 +idna==3.6 # via requests imagesize==1.4.1 # via sphinx @@ -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..15017b083d3 100644 --- a/requirements/doc.in +++ b/requirements/doc.in @@ -1,7 +1,4 @@ --c broken-projects.in - aiohttp-theme sphinx -sphinxcontrib-blockdiag sphinxcontrib-towncrier towncrier diff --git a/requirements/doc.txt b/requirements/doc.txt index e696c59b1a6..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,9 +18,7 @@ click==8.1.7 # via towncrier docutils==0.20.1 # via sphinx -funcparserlib==1.0.1 - # via blockdiag -idna==3.4 +idna==3.6 # via requests imagesize==1.4.1 # via sphinx @@ -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 diff --git a/requirements/test.in b/requirements/test.in index 686cd6dbf2e..a88b54f3532 100644 --- a/requirements/test.in +++ b/requirements/test.in @@ -1,4 +1,3 @@ --c broken-projects.in -r base.in coverage