diff --git a/CHANGES/12549.doc.rst b/CHANGES/12549.doc.rst new file mode 100644 index 00000000000..0288c33cba5 --- /dev/null +++ b/CHANGES/12549.doc.rst @@ -0,0 +1 @@ +Added the :doc:`threat_model` to the Sphinx documentation -- by :user:`omkar-334`. diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt index 84e58805f29..8ec2f50ef1c 100644 --- a/CONTRIBUTORS.txt +++ b/CONTRIBUTORS.txt @@ -292,6 +292,7 @@ Nándor Mátravölgyi Oisin Aylward Olaf Conradi Oleg Höfling +Omkar Kabde Pahaz Blinov Panagiotis Kolokotronis Pankaj Pandey diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md index 1c10ce1e219..3f48765e249 100644 --- a/THREAT_MODEL.md +++ b/THREAT_MODEL.md @@ -1,4 +1,4 @@ -# aiohttp Threat Model +# Threat Model This document is a STRIDE-based threat model for the [aiohttp](https://github.com/aio-libs/aiohttp) library. It is a living document @@ -310,5 +310,3 @@ into `StreamReader`) is then handed to `web_protocol.RequestHandler` and request parser (strict). These are all currently in place; this section assumes no regression. - ---- diff --git a/docs/conf.py b/docs/conf.py index 505359b917e..a3254645cfb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,6 +59,8 @@ "sphinx.ext.intersphinx", "sphinx.ext.viewcode", # Third-party extensions: + "myst_parser", # renders Markdown sources (e.g. ``THREAT_MODEL.md``) + "sphinxcontrib.mermaid", # renders the Mermaid flowcharts in ``THREAT_MODEL.md`` "sphinxcontrib.towncrier.ext", # provides `towncrier-draft-entries` directive ] @@ -70,6 +72,23 @@ except ImportError: pass +spelling_exclude_patterns = [ + # THREAT_MODEL.md is already spell-checked by the codespell pre-commit hook. + # The spelling builder additionally mis-tokenises its ``**S**poofing`` STRIDE + # list into non-words, so skip the threat model here to avoid double coverage. + "threat_model.md", +] + + +# -- MyST (Markdown) configuration ---------------------------------------- + +# ``THREAT_MODEL.md`` lives at the repo root and is surfaced through +# ``docs/threat_model.md``. +myst_heading_anchors = 3 # anchors for h1-h3 so the in-page section links work +myst_fence_as_directive = ["mermaid"] # render ```mermaid fences as diagrams + +# TODO: Remove this option once THREAT_MODEL.md is complete. +suppress_warnings = ["myst.xref_missing"] intersphinx_mapping = { "pytest": ("http://docs.pytest.org/en/latest/", None), diff --git a/docs/index.rst b/docs/index.rst index 39b95cb1b61..95a61c0de87 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -231,3 +231,4 @@ Table Of Contents misc external contributing + threat_model diff --git a/docs/threat_model.md b/docs/threat_model.md new file mode 100644 index 00000000000..f585a70ff9e --- /dev/null +++ b/docs/threat_model.md @@ -0,0 +1,2 @@ +```{include} ../THREAT_MODEL.md +``` diff --git a/requirements/constraints.txt b/requirements/constraints.txt index 5d9fdef148b..1f0f55aeff8 100644 --- a/requirements/constraints.txt +++ b/requirements/constraints.txt @@ -32,7 +32,9 @@ async-timeout==5.0.1 ; python_version < "3.11" # aiohttp # valkey attrs==26.1.0 - # via aiohttp + # via + # aiohttp + # myst-parser babel==2.18.0 # via sphinx backports-asyncio-runner==1.2.0 @@ -76,7 +78,9 @@ cython==3.2.4 distlib==0.4.0 # via virtualenv docutils==0.21.2 - # via sphinx + # via + # myst-parser + # sphinx exceptiongroup==1.3.1 # via pytest execnet==2.1.2 @@ -115,14 +119,21 @@ isal==1.7.2 ; python_version < "3.14" and implementation_name == "cpython" # -r requirements/test-common.in jinja2==3.1.6 # via + # myst-parser # sphinx + # sphinxcontrib-mermaid # towncrier librt==0.11.0 # via mypy -markdown-it-py==4.2.0 - # via rich +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser + # rich markupsafe==3.0.3 # via jinja2 +mdit-py-plugins==0.6.1 + # via myst-parser mdurl==0.1.2 # via markdown-it-py multidict==6.7.1 @@ -137,6 +148,8 @@ mypy==2.1.0 ; implementation_name == "cpython" # -r requirements/test-common.in mypy-extensions==1.1.0 # via mypy +myst-parser==4.0.1 + # via -r requirements/doc.in nodeenv==1.10.0 # via pre-commit packaging==26.2 @@ -230,7 +243,10 @@ python-on-whales==0.81.0 # -r requirements/lint.in # -r requirements/test-common.in pyyaml==6.0.3 - # via pre-commit + # via + # myst-parser + # pre-commit + # sphinxcontrib-mermaid requests==2.34.2 # via # sphinx @@ -248,6 +264,8 @@ snowballstemmer==3.0.1 sphinx==8.1.3 # via # -r requirements/doc.in + # myst-parser + # sphinxcontrib-mermaid # sphinxcontrib-spelling # sphinxcontrib-towncrier sphinxcontrib-applehelp==2.0.0 @@ -258,6 +276,8 @@ sphinxcontrib-htmlhelp==2.1.0 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx +sphinxcontrib-mermaid==2.0.2 + # via -r requirements/doc.in sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 diff --git a/requirements/dev.txt b/requirements/dev.txt index 2253454c89a..2dc3b32244e 100644 --- a/requirements/dev.txt +++ b/requirements/dev.txt @@ -32,7 +32,9 @@ async-timeout==5.0.1 ; python_version < "3.11" # aiohttp # valkey attrs==26.1.0 - # via aiohttp + # via + # aiohttp + # myst-parser babel==2.18.0 # via sphinx backports-asyncio-runner==1.2.0 @@ -74,7 +76,9 @@ cryptography==48.0.0 distlib==0.4.0 # via virtualenv docutils==0.21.2 - # via sphinx + # via + # myst-parser + # sphinx exceptiongroup==1.3.1 # via pytest execnet==2.1.2 @@ -113,14 +117,21 @@ isal==1.7.2 ; python_version < "3.14" and implementation_name == "cpython" # -r requirements/test-common.in jinja2==3.1.6 # via + # myst-parser # sphinx + # sphinxcontrib-mermaid # towncrier librt==0.11.0 # via mypy -markdown-it-py==4.2.0 - # via rich +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser + # rich markupsafe==3.0.3 # via jinja2 +mdit-py-plugins==0.6.1 + # via myst-parser mdurl==0.1.2 # via markdown-it-py multidict==6.7.1 @@ -134,6 +145,8 @@ mypy==2.1.0 ; implementation_name == "cpython" # -r requirements/test-common.in mypy-extensions==1.1.0 # via mypy +myst-parser==4.0.1 + # via -r requirements/doc.in nodeenv==1.10.0 # via pre-commit packaging==26.2 @@ -225,7 +238,10 @@ python-on-whales==0.81.0 # -r requirements/lint.in # -r requirements/test-common.in pyyaml==6.0.3 - # via pre-commit + # via + # myst-parser + # pre-commit + # sphinxcontrib-mermaid requests==2.34.2 # via sphinx rich==15.0.0 @@ -241,6 +257,8 @@ snowballstemmer==3.0.1 sphinx==8.1.3 # via # -r requirements/doc.in + # myst-parser + # sphinxcontrib-mermaid # sphinxcontrib-towncrier sphinxcontrib-applehelp==2.0.0 # via sphinx @@ -250,6 +268,8 @@ sphinxcontrib-htmlhelp==2.1.0 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx +sphinxcontrib-mermaid==2.0.2 + # via -r requirements/doc.in sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 diff --git a/requirements/doc-spelling.txt b/requirements/doc-spelling.txt index eb528786532..e653ba3adea 100644 --- a/requirements/doc-spelling.txt +++ b/requirements/doc-spelling.txt @@ -17,23 +17,41 @@ charset-normalizer==3.4.7 click==8.4.0 # via towncrier docutils==0.21.2 - # via sphinx + # via + # myst-parser + # sphinx idna==3.15 # via requests imagesize==2.0.0 # via sphinx jinja2==3.1.6 # via + # myst-parser # sphinx + # sphinxcontrib-mermaid # towncrier +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser markupsafe==3.0.3 # via jinja2 +mdit-py-plugins==0.6.1 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +myst-parser==4.0.1 + # via -r requirements/doc.in packaging==26.2 # via sphinx pyenchant==3.3.0 # via sphinxcontrib-spelling pygments==2.20.0 # via sphinx +pyyaml==6.0.3 + # via + # myst-parser + # sphinxcontrib-mermaid requests==2.34.2 # via # sphinx @@ -43,6 +61,8 @@ snowballstemmer==3.0.1 sphinx==8.1.3 # via # -r requirements/doc.in + # myst-parser + # sphinxcontrib-mermaid # sphinxcontrib-spelling # sphinxcontrib-towncrier sphinxcontrib-applehelp==2.0.0 @@ -53,6 +73,8 @@ sphinxcontrib-htmlhelp==2.1.0 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx +sphinxcontrib-mermaid==2.0.2 + # via -r requirements/doc.in sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 diff --git a/requirements/doc.in b/requirements/doc.in index 15017b083d3..7106c3808d9 100644 --- a/requirements/doc.in +++ b/requirements/doc.in @@ -1,4 +1,6 @@ aiohttp-theme +myst-parser sphinx +sphinxcontrib-mermaid sphinxcontrib-towncrier towncrier diff --git a/requirements/doc.txt b/requirements/doc.txt index 9ec45e626e2..28ea7be44a3 100644 --- a/requirements/doc.txt +++ b/requirements/doc.txt @@ -17,21 +17,39 @@ charset-normalizer==3.4.7 click==8.4.0 # via towncrier docutils==0.21.2 - # via sphinx + # via + # myst-parser + # sphinx idna==3.15 # via requests imagesize==2.0.0 # via sphinx jinja2==3.1.6 # via + # myst-parser # sphinx + # sphinxcontrib-mermaid # towncrier +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser markupsafe==3.0.3 # via jinja2 +mdit-py-plugins==0.6.1 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +myst-parser==4.0.1 + # via -r requirements/doc.in packaging==26.2 # via sphinx pygments==2.20.0 # via sphinx +pyyaml==6.0.3 + # via + # myst-parser + # sphinxcontrib-mermaid requests==2.34.2 # via sphinx snowballstemmer==3.0.1 @@ -39,6 +57,8 @@ snowballstemmer==3.0.1 sphinx==8.1.3 # via # -r requirements/doc.in + # myst-parser + # sphinxcontrib-mermaid # sphinxcontrib-towncrier sphinxcontrib-applehelp==2.0.0 # via sphinx @@ -48,6 +68,8 @@ sphinxcontrib-htmlhelp==2.1.0 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx +sphinxcontrib-mermaid==2.0.2 + # via -r requirements/doc.in sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0