From 9a44e4527704f17cca158b260b68a8dd37f95970 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 1 Nov 2020 18:23:24 +0900 Subject: Fix #7613: autodoc: autodoc does not respect __signature__ of the class --- CHANGES | 1 + sphinx/ext/autodoc/__init__.py | 7 +++- tests/roots/test-ext-autodoc/target/classes.py | 11 ++++++ tests/test_ext_autodoc_autoclass.py | 50 ++++++++++++++++++++++++++ tests/test_ext_autodoc_autofunction.py | 8 +++++ 5 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 tests/test_ext_autodoc_autoclass.py diff --git a/CHANGES b/CHANGES index ca79187f7..f181af9d3 100644 --- a/CHANGES +++ b/CHANGES @@ -52,6 +52,7 @@ Bugs fixed * #7786: autodoc: can't detect overloaded methods defined in other file * #8294: autodoc: single-string __slots__ is not handled correctly * #7785: autodoc: autodoc_typehints='none' does not effect to overloaded functions +* #7613: autodoc: autodoc does not respect __signature__ of the class * #8192: napoleon: description is disappeared when it contains inline literals * #8142: napoleon: Potential of regex denial of service in google style docs * #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 7343d41b6..3f2495882 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -1391,7 +1391,12 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type: # This sequence is copied from inspect._signature_from_callable. # ValueError means that no signature could be found, so we keep going. - # First, let's see if it has an overloaded __call__ defined + # First, we check the obj has a __signature__ attribute + if (hasattr(self.object, '__signature__') and + isinstance(self.object.__signature__, Signature)): + return None, None, self.object.__signature__ + + # Next, let's see if it has an overloaded __call__ defined # in its metaclass call = get_user_defined_function_or_method(type(self.object), '__call__') diff --git a/tests/roots/test-ext-autodoc/target/classes.py b/tests/roots/test-ext-autodoc/target/classes.py index dc471a6f3..52c23748b 100644 --- a/tests/roots/test-ext-autodoc/target/classes.py +++ b/tests/roots/test-ext-autodoc/target/classes.py @@ -1,3 +1,6 @@ +from inspect import Parameter, Signature + + class Foo: pass @@ -10,3 +13,11 @@ class Bar: class Baz: def __new__(cls, x, y): pass + + +class Qux: + __signature__ = Signature(parameters=[Parameter('foo', Parameter.POSITIONAL_OR_KEYWORD), + Parameter('bar', Parameter.POSITIONAL_OR_KEYWORD)]) + + def __init__(self, x, y): + pass diff --git a/tests/test_ext_autodoc_autoclass.py b/tests/test_ext_autodoc_autoclass.py new file mode 100644 index 000000000..89a79c2c7 --- /dev/null +++ b/tests/test_ext_autodoc_autoclass.py @@ -0,0 +1,50 @@ +""" + test_ext_autodoc_autoclass + ~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Test the autodoc extension. This tests mainly the Documenters; the auto + directives are tested in a test source file translated by test_build. + + :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import pytest + +from test_ext_autodoc import do_autodoc + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_classes(app): + actual = do_autodoc(app, 'function', 'target.classes.Foo') + assert list(actual) == [ + '', + '.. py:function:: Foo()', + ' :module: target.classes', + '', + ] + + actual = do_autodoc(app, 'function', 'target.classes.Bar') + assert list(actual) == [ + '', + '.. py:function:: Bar(x, y)', + ' :module: target.classes', + '', + ] + + actual = do_autodoc(app, 'function', 'target.classes.Baz') + assert list(actual) == [ + '', + '.. py:function:: Baz(x, y)', + ' :module: target.classes', + '', + ] + + actual = do_autodoc(app, 'function', 'target.classes.Qux') + assert list(actual) == [ + '', + '.. py:function:: Qux(foo, bar)', + ' :module: target.classes', + '', + ] + diff --git a/tests/test_ext_autodoc_autofunction.py b/tests/test_ext_autodoc_autofunction.py index bb292bc6a..64f6e8db3 100644 --- a/tests/test_ext_autodoc_autofunction.py +++ b/tests/test_ext_autodoc_autofunction.py @@ -40,6 +40,14 @@ def test_classes(app): '', ] + actual = do_autodoc(app, 'function', 'target.classes.Qux') + assert list(actual) == [ + '', + '.. py:function:: Qux(foo, bar)', + ' :module: target.classes', + '', + ] + @pytest.mark.sphinx('html', testroot='ext-autodoc') def test_callable(app): -- cgit v1.2.1 From 9f1c89dd9d5139dfa8af43f9b552d549fb93d910 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Tue, 3 Nov 2020 11:39:44 +0900 Subject: Update CHANGES for PR #8355 --- CHANGES | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 3e5836a15..54f4bdc3d 100644 --- a/CHANGES +++ b/CHANGES @@ -41,6 +41,8 @@ Features added Bugs fixed ---------- +* #7613: autodoc: autodoc does not respect __signature__ of the class + Testing -------- @@ -94,7 +96,6 @@ Bugs fixed * #7786: autodoc: can't detect overloaded methods defined in other file * #8294: autodoc: single-string __slots__ is not handled correctly * #7785: autodoc: autodoc_typehints='none' does not effect to overloaded functions -* #7613: autodoc: autodoc does not respect __signature__ of the class * #8192: napoleon: description is disappeared when it contains inline literals * #8142: napoleon: Potential of regex denial of service in google style docs * #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex -- cgit v1.2.1 From e84a7ac659cc9a6ba6bb6765b784c5be9b5a16dd Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 4 Nov 2020 22:07:28 +0900 Subject: Do testing at GitHub Actions --- .github/workflows/main.yml | 33 +++++++++++++++++++++++++++++++-- .travis.yml | 6 ------ 2 files changed, 31 insertions(+), 8 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 7acfef6d2..1750a764a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -1,9 +1,38 @@ -name: CI on Windows +name: CI on: [push, pull_request] jobs: - build: + ubuntu: + runs-on: ubuntu-16.04 + strategy: + fail-fast: false + matrix: + name: [py36, py37] + include: + - name: py36 + python: 3.6 + docutils: du13 + - name: py37 + python: 3.7 + docutils: du14 + + steps: + - uses: actions/checkout@v2 + - name: Set up Python ${{ matrix.python }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python }} + - name: Check Python version + run: python --version + - name: Install graphviz + run: sudo apt-get install graphviz + - name: Install dependencies + run: pip install -U tox + - name: Run Tox + run: tox -e ${{ matrix.docutils }} -- -vv + + windows: runs-on: windows-latest strategy: matrix: diff --git a/.travis.yml b/.travis.yml index 47a8e7c7a..8e971a356 100644 --- a/.travis.yml +++ b/.travis.yml @@ -14,12 +14,6 @@ jobs: - python: '3.5' env: - TOXENV=du12 - - python: '3.6' - env: - - TOXENV=du13 - - python: '3.7' - env: - - TOXENV=du14 - python: '3.8' env: - TOXENV=du15 -- cgit v1.2.1 From 242c63dc8bb22ee4aab769eafee129b293aeaf01 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 4 Nov 2020 22:07:28 +0900 Subject: Do testing at GitHub Actions --- .github/workflows/main.yml | 33 +++++++++++++++++++++++++++++++-- .travis.yml | 6 ------ 2 files changed, 31 insertions(+), 8 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 7acfef6d2..1750a764a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -1,9 +1,38 @@ -name: CI on Windows +name: CI on: [push, pull_request] jobs: - build: + ubuntu: + runs-on: ubuntu-16.04 + strategy: + fail-fast: false + matrix: + name: [py36, py37] + include: + - name: py36 + python: 3.6 + docutils: du13 + - name: py37 + python: 3.7 + docutils: du14 + + steps: + - uses: actions/checkout@v2 + - name: Set up Python ${{ matrix.python }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python }} + - name: Check Python version + run: python --version + - name: Install graphviz + run: sudo apt-get install graphviz + - name: Install dependencies + run: pip install -U tox + - name: Run Tox + run: tox -e ${{ matrix.docutils }} -- -vv + + windows: runs-on: windows-latest strategy: matrix: diff --git a/.travis.yml b/.travis.yml index 47a8e7c7a..8e971a356 100644 --- a/.travis.yml +++ b/.travis.yml @@ -14,12 +14,6 @@ jobs: - python: '3.5' env: - TOXENV=du12 - - python: '3.6' - env: - - TOXENV=du13 - - python: '3.7' - env: - - TOXENV=du14 - python: '3.8' env: - TOXENV=du15 -- cgit v1.2.1 From 218de39462798c8e102ff375b8ee9fb336537041 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 4 Nov 2020 23:19:25 +0900 Subject: Fix testcases for singledispatch are sometimes failed They are sometimes failed with python3.5 because the order of singledispatch functions is not stable on python 3.5. This uses comparision via "in" keyword to check the signature of singledispatch functions stably. --- tests/test_ext_autodoc.py | 33 ++++++++++++++++++++------------- tests/test_ext_autodoc_autofunction.py | 29 +++++++++++++++++++---------- 2 files changed, 39 insertions(+), 23 deletions(-) diff --git a/tests/test_ext_autodoc.py b/tests/test_ext_autodoc.py index c0676f23f..703cc13f6 100644 --- a/tests/test_ext_autodoc.py +++ b/tests/test_ext_autodoc.py @@ -1832,19 +1832,26 @@ def test_autodoc_for_egged_code(app): def test_singledispatch(app): options = {"members": None} actual = do_autodoc(app, 'module', 'target.singledispatch', options) - assert list(actual) == [ - '', - '.. py:module:: target.singledispatch', - '', - '', - '.. py:function:: func(arg, kwarg=None)', - ' func(arg: int, kwarg=None)', - ' func(arg: str, kwarg=None)', - ' :module: target.singledispatch', - '', - ' A function for general use.', - '', - ] + if sys.version_info < (3, 6): + # check the result via "in" because the order of singledispatch signatures is + # usually changed (because dict is not OrderedDict yet!) + assert '.. py:function:: func(arg, kwarg=None)' in actual + assert ' func(arg: int, kwarg=None)' in actual + assert ' func(arg: str, kwarg=None)' in actual + else: + assert list(actual) == [ + '', + '.. py:module:: target.singledispatch', + '', + '', + '.. py:function:: func(arg, kwarg=None)', + ' func(arg: int, kwarg=None)', + ' func(arg: str, kwarg=None)', + ' :module: target.singledispatch', + '', + ' A function for general use.', + '', + ] @pytest.mark.skipif(sys.version_info < (3, 8), diff --git a/tests/test_ext_autodoc_autofunction.py b/tests/test_ext_autodoc_autofunction.py index bb292bc6a..1f68c0319 100644 --- a/tests/test_ext_autodoc_autofunction.py +++ b/tests/test_ext_autodoc_autofunction.py @@ -9,6 +9,8 @@ :license: BSD, see LICENSE for details. """ +import sys + import pytest from test_ext_autodoc import do_autodoc @@ -108,16 +110,23 @@ def test_decorated(app): def test_singledispatch(app): options = {} actual = do_autodoc(app, 'function', 'target.singledispatch.func', options) - assert list(actual) == [ - '', - '.. py:function:: func(arg, kwarg=None)', - ' func(arg: int, kwarg=None)', - ' func(arg: str, kwarg=None)', - ' :module: target.singledispatch', - '', - ' A function for general use.', - '', - ] + if sys.version_info < (3, 6): + # check the result via "in" because the order of singledispatch signatures is + # usually changed (because dict is not OrderedDict yet!) + assert '.. py:function:: func(arg, kwarg=None)' in actual + assert ' func(arg: int, kwarg=None)' in actual + assert ' func(arg: str, kwarg=None)' in actual + else: + assert list(actual) == [ + '', + '.. py:function:: func(arg, kwarg=None)', + ' func(arg: int, kwarg=None)', + ' func(arg: str, kwarg=None)', + ' :module: target.singledispatch', + '', + ' A function for general use.', + '', + ] @pytest.mark.sphinx('html', testroot='ext-autodoc') -- cgit v1.2.1 From 4478f00c4cc2f813d8b62148813bf0dcc734c7e1 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 4 Nov 2020 23:21:52 +0900 Subject: Do testing with python3.5 at GitHub Actions --- .github/workflows/main.yml | 5 ++++- .travis.yml | 3 --- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 1750a764a..a85e3c8fb 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -8,8 +8,11 @@ jobs: strategy: fail-fast: false matrix: - name: [py36, py37] + name: [py35, py36, py37] include: + - name: py35 + python: 3.5 + docutils: du12 - name: py36 python: 3.6 docutils: du13 diff --git a/.travis.yml b/.travis.yml index 8e971a356..4123ba6b5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -11,9 +11,6 @@ env: jobs: include: - - python: '3.5' - env: - - TOXENV=du12 - python: '3.8' env: - TOXENV=du15 -- cgit v1.2.1 From 0cf1632edf8e4f16796b4324be7de11b99853734 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 5 Nov 2020 01:53:42 +0900 Subject: Update CHANGES for PR #8355 --- CHANGES | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index 54f4bdc3d..4d412799a 100644 --- a/CHANGES +++ b/CHANGES @@ -20,6 +20,8 @@ Features added Bugs fixed ---------- +* #7613: autodoc: autodoc does not respect __signature__ of the class + Testing -------- @@ -41,8 +43,6 @@ Features added Bugs fixed ---------- -* #7613: autodoc: autodoc does not respect __signature__ of the class - Testing -------- -- cgit v1.2.1