FIX: coroutines can have a return statement (#542)

* FIX: coroutines can have a return statement

The value returned by the coroutine is carried on the `StopIteration` Exception
that is raised when exhausted.

* CI: do not test Sphinx 7.3

* CI: also do not do sphinx 7.3.x on pre-release

* CI: also do not use sphinx 7.3 on docs

* STY: placate linter

Author: tacaswell

.circleci/config.yml

@@ -21,6 +21,7 @@ jobs:
             source venv/bin/activate
             python -m pip install --upgrade pip wheel setuptools
             python -m pip install --upgrade -r requirements/doc.txt
+            python -m pip install 'sphinx!=7.3.*'
             python -m pip list
       - save_cache:
           key: pip-cache

.github/workflows/test.yml

@@ -18,7 +18,10 @@ jobs:
         os: [Ubuntu]
         python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
         sphinx-version:
-          ["sphinx==6.0", "sphinx==6.2", "sphinx==7.0", "sphinx>=7.2"]
+          ["sphinx==6.0", "sphinx==6.2", "sphinx==7.0", "'sphinx>=7.2,<7.3'"]
+        exclude:
+          - python-version: "3.8"
+            sphinx-version: "'sphinx>=7.2,<7.3'"
     steps:
       - uses: actions/checkout@v4
 
@@ -84,6 +87,7 @@ jobs:
           python -m pip install --upgrade pip wheel setuptools
           python -m pip install --pre -r requirements/test.txt -r requirements/doc.txt
           python -m pip install codecov
+          python -m pip install 'sphinx!=7.3.*'
           python -m pip list
 
       - name: Install

numpydoc/docscrape.py

@@ -394,12 +394,8 @@ def _parse(self):
         sections = list(self._read_sections())
         section_names = {section for section, content in sections}
 
-        has_returns = "Returns" in section_names
         has_yields = "Yields" in section_names
         # We could do more tests, but we are not. Arbitrarily.
-        if has_returns and has_yields:
-            msg = "Docstring contains both a Returns and Yields section."
-            raise ValueError(msg)
         if not has_yields and "Receives" in section_names:
             msg = "Docstring contains a Receives section but not Yields."
             raise ValueError(msg)

numpydoc/tests/test_docscrape.py

@@ -279,7 +279,9 @@ def test_returnyield():
     The number of bananas.
 
 """
-    assert_raises(ValueError, NumpyDocString, doc_text)
+    doc = NumpyDocString(doc_text)
+    assert len(doc["Returns"]) == 1
+    assert len(doc["Yields"]) == 2
 
 
 def test_section_twice():