=========
Usage
=========

.. extensions:: sphinx_autofixture


.. rst:directive:: autofixture

	Directive to automatically document a pytest fixture.

	**Example:**

	.. code-block:: python

		@pytest.fixture()
		def tmp_pathplus(tmp_path: Path) -> PathPlus:
			"""
			Pytest fixture that returns a temporary directory in the form of a
			:class:`~domdf_python_tools.paths.PathPlus` object.

			The directory is unique to each test function invocation,
			created as a sub directory of the base temporary directory.

			Use it as follows:

			.. code-block:: python

				pytest_plugins = ("coincidence", )

				def test_something(tmp_pathplus: PathPlus):
					assert True

			:rtype:

			.. versionadded:: 0.10.0
			"""  # noqa: D400

			return PathPlus(tmp_path)

	.. rest-example::

		.. autofixture:: coincidence.tmp_pathplus


	.. tip:: :rst:dir:`autofixture` can also be used with :rst:dir:`automodule`.

	.. seealso:: `The documentation for coincidence`_ has an an example with the ReadTheDocs Sphinx theme.

	.. _The documentation for coincidence: https://coincidence.readthedocs.io/en/latest/api/fixtures.html


.. rst:role:: fixture

	Role that provides a cross-reference to the documentation generated by :rst:dir:`autofixture`.