Implement future changelog previews in the docs (#6055)

webknjaz · web-flow · commit 079e9c5a7e6f · 2021-10-06T10:00:35.000+02:00
* Implement future changelog previews in the docs

* Self-install on RTD

* Fix spelling mistakes in the check notes
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,5 +1,21 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+# for details
+
+---
+version: 2
+
+submodules:
+  include: all  # []
+  exclude: []
+  recursive: true
+
 build:
   image: latest
 python:
-  version: 3.6
-  pip_install: false
+  version: 3.8
+  install:
+  - method: pip
+    path: .
+  - requirements: requirements/doc.txt
+...
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,7 +1,3 @@
-=========
-Changelog
-=========
-
 ..
     You should *NOT* be adding new change log entries to this file, this
     file is managed by towncrier. You *may* edit previous change logs to
diff --git a/CHANGES/3559.doc b/CHANGES/3559.doc
@@ -1 +1 @@
-Clarified WebSocketResponse closure in quickstart example.
+Clarified ``WebSocketResponse`` closure in the quick start example.
diff --git a/CHANGES/3828.feature b/CHANGES/3828.feature
@@ -1,4 +1,4 @@
-Disable implicit switch-back to pure python mode. The build fails loudly if aiohttp
-cannot be compiled with C Accellerators.  Use AIOHTTP_NO_EXTENSIONS=1 to explicitly
+Disabled implicit switch-back to pure python mode. The build fails loudly if aiohttp
+cannot be compiled with C Accelerators.  Use `AIOHTTP_NO_EXTENSIONS=1` to explicitly
 disable C Extensions complication and switch to Pure-Python mode.  Note that Pure-Python
 mode is significantly slower than compiled one.
diff --git a/CHANGES/4054.feature b/CHANGES/4054.feature
@@ -1 +1 @@
-Implemented readuntil in StreamResponse
+Implemented ``readuntil`` in ``StreamResponse``
diff --git a/CHANGES/4277.feature b/CHANGES/4277.feature
@@ -1 +1 @@
-Add set_cookie and del_cookie methods to HTTPException
+Added ``set_cookie`` and ``del_cookie`` methods to ``HTTPException``
diff --git a/CHANGES/4299.bugfix b/CHANGES/4299.bugfix
@@ -1 +1 @@
-Delete older code in example (examples/web_classview.py)
+Delete older code in example (:file:`examples/web_classview.py`)
diff --git a/CHANGES/4302.bugfix b/CHANGES/4302.bugfix
@@ -1 +1 @@
-Fixed the support of route handlers wrapped by functools.partial()
+Fixed the support of route handlers wrapped by :py:func:`functools.partial`
diff --git a/CHANGES/4452.doc b/CHANGES/4452.doc
@@ -1 +1 @@
-Fix typo in client_quickstart docs.
+Fixed a typo in the ``client_quickstart`` doc.
diff --git a/CHANGES/4700.feature b/CHANGES/4700.feature
@@ -1,6 +1,6 @@
-AioHTTPTestCase is more async friendly now.
+``AioHTTPTestCase`` is more async friendly now.
 
-For people who use unittest and are used to use unittest.TestCase
-it will be easier to write new test cases like the sync version of the TestCase class,
+For people who use unittest and are used to use :py:exc:`~unittest.TestCase`
+it will be easier to write new test cases like the sync version of the :py:exc:`~unittest.TestCase` class,
 without using the decorator `@unittest_run_loop`, just `async def test_*`.
-The only difference is that for the people using python3.7 and below a new dependency is needed, it is `asynctestcase`.
+The only difference is that for the people using python3.7 and below a new dependency is needed, it is ``asynctestcase``.
diff --git a/CHANGES/5326.doc b/CHANGES/5326.doc
@@ -1 +1 @@
-Refactor OpenAPI/Swagger aiohttp addons, added aio-openapi
+Refactored OpenAPI/Swagger aiohttp addons, added ``aio-openapi``
diff --git a/CHANGES/5783.feature b/CHANGES/5783.feature
@@ -1 +1 @@
-Started keeping the ``Authorization`` header during http->https redirects when the host remains the same.
+Started keeping the ``Authorization`` header during HTTP -> HTTPS redirects when the host remains the same.
diff --git a/CHANGES/5905.bugfix b/CHANGES/5905.bugfix
@@ -1 +1 @@
-remove deprecated loop argument for asnycio.sleep/gather calls
+Removed the deprecated ``loop`` argument from the ``asyncio.sleep``/``gather`` calls
diff --git a/docs/changes.rst b/docs/changes.rst
@@ -1,5 +1,17 @@
 .. _aiohttp_changes:
 
+=========
+Changelog
+=========
+
+To be included in v\ |release| (if present)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. towncrier-draft-entries:: |release| [UNRELEASED DRAFT]
+
+Released versions
+^^^^^^^^^^^^^^^^^
+
 .. include:: ../CHANGES.rst
 
 .. include:: ../HISTORY.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -14,6 +14,9 @@
 
 import os
 import re
+from pathlib import Path
+
+PROJECT_ROOT_DIR = Path(__file__).parents[1].resolve()
 
 _docs_path = os.path.dirname(__file__)
 _version_path = os.path.abspath(
@@ -50,6 +53,7 @@
     # Third-party extensions:
     "sphinxcontrib.asyncio",
     "sphinxcontrib.blockdiag",
+    "sphinxcontrib.towncrier",  # provides `towncrier-draft-entries` directive
 ]
 
 
@@ -420,3 +424,10 @@
     ("py:meth", "aiohttp.web.UrlDispatcher.register_resource"),  # undocumented
     ("py:func", "aiohttp_debugtoolbar.setup"),  # undocumented
 ]
+
+# -- Options for towncrier_draft extension -----------------------------------
+
+towncrier_draft_autoversion_mode = "draft"  # or: 'sphinx-version', 'sphinx-release'
+towncrier_draft_include_empty = True
+towncrier_draft_working_directory = PROJECT_ROOT_DIR
+# Not yet supported: towncrier_draft_config_path = 'pyproject.toml'  # relative to cwd
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
@@ -82,6 +82,7 @@ WSMsgType
 Websockets
 Workflow
 abc
+addons
 aiodns
 aioes
 aiohttp
@@ -117,6 +118,7 @@ brotli
 bugfix
 builtin
 cChardet
+callables
 cancelled
 canonicalization
 canonicalize
@@ -204,6 +206,7 @@ login
 lookup
 lookups
 lossless
+lowercased
 manylinux
 metadata
 microservice
@@ -261,6 +264,7 @@ redirections
 refactor
 refactored
 refactoring
+referenceable
 regex
 regexps
 regexs
@@ -319,6 +323,7 @@ unittest
 unix
 unsets
 unstripped
+uppercased
 upstr
 url
 urldispatcher
diff --git a/requirements/dev.txt b/requirements/dev.txt
@@ -61,7 +61,7 @@ click==7.1.2
     #   towncrier
 click-default-group==1.2.2
     # via towncrier
-coverage==5.5
+coverage[toml]==6.0
     # via
     #   -r requirements/test.txt
     #   pytest-cov
@@ -128,7 +128,7 @@ mccabe==0.6.1
     # via
     #   -r requirements/lint.txt
     #   flake8
-multidict==5.1.0
+multidict==5.2.0
     # via
     #   -r requirements/multidict.txt
     #   yarl
@@ -198,7 +198,7 @@ pytest==6.2.2
     #   -r requirements/test.txt
     #   pytest-cov
     #   pytest-mock
-pytest-cov==2.12.1
+pytest-cov==3.0.0
     # via -r requirements/test.txt
 pytest-mock==3.6.1
     # via -r requirements/test.txt
@@ -236,6 +236,7 @@ sphinx==4.2.0
     #   -r requirements/doc.txt
     #   sphinxcontrib-asyncio
     #   sphinxcontrib-blockdiag
+    #   sphinxcontrib-towncrier
 sphinxcontrib-applehelp==1.0.2
     # via sphinx
 sphinxcontrib-asyncio==0.3.0
@@ -252,21 +253,25 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
+sphinxcontrib-towncrier==0.2.0a0
+    # via -r requirements/doc.txt
 toml==0.10.2
     # via
     #   -r requirements/lint.txt
     #   cherry-picker
     #   mypy
     #   pre-commit
     #   pytest
-    #   pytest-cov
     #   towncrier
 tomli==1.2.1
     # via
     #   -r requirements/lint.txt
     #   black
+    #   coverage
 towncrier==21.3.0
-    # via -r requirements/doc.txt
+    # via
+    #   -r requirements/doc.txt
+    #   sphinxcontrib-towncrier
 trustme==0.9.0 ; platform_machine != "i686"
     # via -r requirements/test.txt
 types-chardet==0.1.3
diff --git a/requirements/doc-spelling.txt b/requirements/doc-spelling.txt
@@ -64,6 +64,7 @@ sphinx==4.2.0
     #   sphinxcontrib-asyncio
     #   sphinxcontrib-blockdiag
     #   sphinxcontrib-spelling
+    #   sphinxcontrib-towncrier
 sphinxcontrib-applehelp==1.0.2
     # via sphinx
 sphinxcontrib-asyncio==0.3.0
@@ -82,10 +83,14 @@ sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
 sphinxcontrib-spelling==7.2.1 ; platform_system != "Windows"
     # via -r requirements/doc-spelling.in
+sphinxcontrib-towncrier==0.2.0a0
+    # via -r requirements/doc.txt
 toml==0.10.2
     # via towncrier
 towncrier==21.3.0
-    # via -r requirements/doc.txt
+    # via
+    #   -r requirements/doc.txt
+    #   sphinxcontrib-towncrier
 urllib3==1.26.5
     # via requests
 webcolors==1.11.1
diff --git a/requirements/doc.txt b/requirements/doc.txt
@@ -5,4 +5,5 @@ pygments==2.10.0
 sphinx==4.2.0
 sphinxcontrib-asyncio==0.3.0
 sphinxcontrib-blockdiag==2.0.0
+sphinxcontrib-towncrier==0.2.0a0
 towncrier==21.3.0

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Clarified WebSocketResponse closure in quickstart example.`
	`1`	+Clarified ``WebSocketResponse`` closure in the quick start example.
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Implemented readuntil in StreamResponse`
	`1`	+Implemented ``readuntil`` in ``StreamResponse``
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Add set_cookie and del_cookie methods to HTTPException`
	`1`	+Added ``set_cookie`` and ``del_cookie`` methods to ``HTTPException``
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Delete older code in example (examples/web_classview.py)`
	`1`	+Delete older code in example (:file:`examples/web_classview.py`)
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Fixed the support of route handlers wrapped by functools.partial()`
	`1`	+Fixed the support of route handlers wrapped by :py:func:`functools.partial`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Fix typo in client_quickstart docs.`
	`1`	+Fixed a typo in the ``client_quickstart`` doc.