Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

replace blockdiag with graphviz in docs #9359

Merged
merged 7 commits into from
Oct 1, 2024
Merged

replace blockdiag with graphviz in docs #9359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
13d495f
replace blockdiag with graphviz in docs
Cycloctane Sep 30, 2024
de8c1e7
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Sep 30, 2024
78ffdde
update 9359.contrib.rst
Cycloctane Sep 30, 2024
6314d63
delete broken-projects.in
Cycloctane Oct 1, 2024
349c02d
format
Cycloctane Oct 1, 2024
c8291d5
add graphviz installation to readthedocs build process
Cycloctane Oct 1, 2024
7615b50
fix graphviz installation
Cycloctane Oct 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .readthedocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ build:
os: ubuntu-24.04
tools:
python: "3.11"
apt_packages:
- graphviz

jobs:
post_create_environment:
Expand Down
2 changes: 2 additions & 0 deletions CHANGES/9359.contrib.rst
View file
Open in desktop
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.
2 changes: 1 addition & 1 deletion docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,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
]

Expand Down
140 changes: 100 additions & 40 deletions docs/tracing_reference.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand All @@ -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;
Expand All @@ -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
-------
Expand Down
1 change: 0 additions & 1 deletion requirements/broken-projects.in
View file
Open in desktop

This file was deleted.

18 changes: 1 addition & 17 deletions requirements/constraints.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -294,6 +279,5 @@ pip==24.2
# via pip-tools
setuptools==75.1.0
# via
# blockdiag
# incremental
# pip-tools
18 changes: 1 addition & 17 deletions requirements/dev.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -286,6 +271,5 @@ pip==24.2
# via pip-tools
setuptools==75.1.0
# via
# blockdiag
# incremental
# pip-tools
Loading
Loading