Added code and tests.

Author: domdfcoding

.isort.cfg

@@ -22,4 +22,5 @@ known_third_party =
     pytest-randomly
     pytest-timeout
     requests
+    sphinx
 known_first_party = sphinx_autofixture

doc-source/requirements.txt

@@ -3,7 +3,6 @@ default-values>=0.2.0
 domdf-sphinx-theme>=0.1.0
 extras-require>=0.2.0
 seed-intersphinx-mapping>=0.1.1
-sphinx>=3.0.3
 sphinx-copybutton>=0.2.12
 sphinx-notfound-page>=0.5
 sphinx-prompt>=1.1.0

requirements.txt

@@ -0,0 +1 @@
+sphinx>=3.3.1

sphinx_autofixture/__init__.py

@@ -26,8 +26,163 @@
 #  OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
+# stdlib
+import ast
+import inspect
+from types import FunctionType
+from typing import Any, Dict, Optional, Tuple
+
+# 3rd party
+from sphinx.application import Sphinx
+from sphinx.domains import ObjType
+from sphinx.domains.python import PyClasslike, PyXRefRole
+from sphinx.ext.autodoc import FunctionDocumenter, Options
+from sphinx.ext.autodoc.directive import DocumenterBridge
+from sphinx.locale import _
+
 __author__: str = "Dominic Davis-Foster"
 __copyright__: str = "2020 Dominic Davis-Foster"
 __license__: str = "MIT License"
 __version__: str = "0.0.0"
 __email__: str = "dominic@davis-foster.co.uk"
+
+__all__ = ["FixtureDecoratorFinder", "FixtureDocumenter", "is_fixture", "setup"]
+
+
+class FixtureDecoratorFinder(ast.NodeVisitor):
+	"""
+	:class:`ast.NodeVisitor` for finding pytest fixtures.
+	"""
+
+	def __init__(self):
+
+		#: Is the function a fixture?
+		self.is_fixture = False
+
+		#: If it is, the scope of the fixture.
+		self.scope = "function"
+
+	def visit_FunctionDef(self, node: ast.FunctionDef) -> Any:
+		if node.decorator_list:
+			for deco in node.decorator_list:
+
+				if isinstance(deco, ast.Call):
+					keywords: Dict[str, ast.Constant] = {k.arg: k.value for k in deco.keywords}
+
+					if "scope" in keywords:
+						scope = keywords["scope"]
+						if isinstance(scope, ast.Constant):
+							self.scope = scope.value
+						else:  # pragma: no cover
+							raise NotImplementedError(type(scope))
+
+					deco = deco.func
+				else:
+					self.scope = "function"
+
+				if isinstance(deco, ast.Name):
+					if deco.id == "fixture":
+						self.is_fixture = True
+						return
+				elif isinstance(deco, ast.Attribute):
+					if deco.attr == "fixture":
+						self.is_fixture = True
+						return
+				else:  # pragma: no cover
+					raise NotImplementedError(str(type(deco)))
+
+
+def is_fixture(function: FunctionType) -> Tuple[bool, Optional[str]]:
+	"""
+	Returns whether the given function is a fixture, and the fixture's scope if it is.
+
+	:param function:
+	"""
+
+	visitor = FixtureDecoratorFinder()
+
+	try:
+		visitor.visit(ast.parse(inspect.getsource(function)))
+	except IndentationError:
+		# Triggered when trying to parse a method
+		return False, None
+
+	if not visitor.is_fixture:
+		return False, None
+
+	return True, visitor.scope
+
+
+class FixtureDocumenter(FunctionDocumenter):
+	"""
+	Sphinx autodoc :class:`~sphinx.ext.autodoc.Documenter` for documenting pytest fixtures.
+	"""
+
+	objtype = "fixture"
+	directivetype = "fixture"
+	priority = 20
+	object: FunctionType  # noqa: A003
+
+	def __init__(self, directive: DocumenterBridge, name: str, indent: str = '') -> None:
+		super().__init__(directive, name, indent)
+		self.options = Options(self.options.copy())
+
+	@classmethod
+	def can_document_member(
+			cls,
+			member: Any,
+			membername: str,
+			isattr: bool,
+			parent: Any,
+			) -> bool:
+		"""
+		Called to see if a member can be documented by this documenter.
+
+		:param member: The member being checked.
+		:param membername: The name of the member.
+		:param isattr:
+		:param parent: The parent of the member.
+		"""
+
+		if isinstance(member, FunctionType):
+			return is_fixture(member)[0]
+		else:
+			return False
+
+	def add_directive_header(self, sig: str = '') -> None:
+		"""
+		Add the directive's header.
+
+		:param sig: Unused -- fixtures have no useful signature.
+		"""
+
+		# doc_lines = (self.object.__doc__ or '').splitlines()
+		# docstring = StringList([dedent(doc_lines[0]) + dedent("\n".join(doc_lines))[1:]])
+		# print(docstring)
+		# input(">>>")
+
+		super().add_directive_header('')
+
+		self.add_line('', self.get_sourcename())
+		self.add_line(
+				f"   **Scope:** |nbsp| |nbsp| |nbsp| |nbsp| {is_fixture(self.object)[1]}", self.get_sourcename()
+				)
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+	"""
+	Setup :mod:`sphinx_autofixture`.
+
+	:param app: The Sphinx app.
+	"""
+
+	app.registry.domains["py"].object_types["fixture"] = ObjType(_("fixture"), "fixture", "function", "obj")
+	app.add_directive_to_domain("py", "fixture", PyClasslike)
+	app.add_role_to_domain("py", "fixture", PyXRefRole())
+
+	app.add_autodocumenter(FixtureDocumenter)
+
+	return {
+			"version": __version__,
+			"parallel_read_safe": True,
+			}

tests/test_is_fixture.py

@@ -0,0 +1,85 @@
+import pytest
+from pytest import fixture
+
+from sphinx_autofixture import is_fixture
+
+
+@fixture
+def name():
+	"""
+	:return:
+	"""
+
+
+@fixture()
+def call():
+	"""
+
+	:return:
+	"""
+
+
+@fixture(scope="module")
+def call_scoped():
+	"""
+
+	:return:
+	"""
+
+
+@pytest.fixture
+def pytest_attribute():
+	"""
+	:return:
+	"""
+
+
+@pytest.fixture()
+def pytest_call():
+	"""
+
+	:return:
+	"""
+
+
+@pytest.fixture(scope="module")
+def pytest_call_scoped():
+	"""
+	:return:
+	"""
+
+
+@pytest.mark.parametrize("func, scope", [
+		pytest.param(name, "function", id="name"),
+		pytest.param(call, "function", id="call"),
+		pytest.param(call_scoped, "module", id="call_scoped"),
+		pytest.param(pytest_attribute, "function", id="pytest_attribute"),
+		pytest.param(pytest_call, "function", id="pytest_call"),
+		pytest.param(pytest_call_scoped, "module", id="pytest_call_scoped"),
+		])
+def test_is_fixture(func, scope):
+	assert is_fixture(func) == (True, scope)
+
+
+def function(): pass
+
+
+class Class:
+
+	def method(self): pass
+
+
+def deco(func): return func
+
+@deco
+def decorated(): pass
+
+
+@pytest.mark.parametrize("func", [
+		pytest.param(function, id="function"),
+		pytest.param(decorated, id="decorated"),
+		pytest.param(Class.method, id="Class.method"),
+		pytest.param(Class().method, id="Class().method"),
+		])
+def test_isnt_fixture(func):
+	assert is_fixture(func) == (False, None)