DOC: Added docstrings to fixtures defined in XML I/O, util and pandas…

… modules (pandas-dev#56524)

pandas/conftest.py

@@ -1973,4 +1973,7 @@ def warsaw(request) -> str:
 
 @pytest.fixture
 def arrow_string_storage():
+    """
+    Fixture that lists possible PyArrow values for StringDtype storage field.
+    """
     return ("pyarrow", "pyarrow_numpy")

pandas/tests/io/xml/conftest.py

@@ -5,34 +5,101 @@
 
 @pytest.fixture
 def xml_data_path():
+    """
+    Returns a Path object to the XML example directory.
+
+    Examples
+    --------
+    >>> def test_read_xml(xml_data_path):
+    ...     read_xml(xml_data_path / 'file.xsl')
+    """
     return Path(__file__).parent.parent / "data" / "xml"
 
 
 @pytest.fixture
 def xml_books(xml_data_path, datapath):
+    """
+    Returns the path (as `str`) to the `books.xml` example file.
+
+    Examples
+    --------
+    >>> def test_read_xml(xml_books):
+    ...     read_xml(xml_books)
+    """
     return datapath(xml_data_path / "books.xml")
 
 
 @pytest.fixture
 def xml_doc_ch_utf(xml_data_path, datapath):
+    """
+    Returns the path (as `str`) to the `doc_ch_utf.xml` example file.
+
+    Examples
+    --------
+    >>> def test_read_xml(xml_doc_ch_utf):
+    ...     read_xml(xml_doc_ch_utf)
+    """
     return datapath(xml_data_path / "doc_ch_utf.xml")
 
 
 @pytest.fixture
 def xml_baby_names(xml_data_path, datapath):
+    """
+    Returns the path (as `str`) to the `baby_names.xml` example file.
+
+    Examples
+    --------
+    >>> def test_read_xml(xml_baby_names):
+    ...     read_xml(xml_baby_names)
+    """
     return datapath(xml_data_path / "baby_names.xml")
 
 
 @pytest.fixture
 def kml_cta_rail_lines(xml_data_path, datapath):
+    """
+    Returns the path (as `str`) to the `cta_rail_lines.kml` example file.
+
+    Examples
+    --------
+    >>> def test_read_xml(kml_cta_rail_lines):
+    ...     read_xml(
+    ...         kml_cta_rail_lines,
+    ...         xpath=".//k:Placemark",
+    ...         namespaces={"k": "http://www.opengis.net/kml/2.2"},
+    ...         stylesheet=xsl_flatten_doc,
+    ...     )
+    """
     return datapath(xml_data_path / "cta_rail_lines.kml")
 
 
 @pytest.fixture
 def xsl_flatten_doc(xml_data_path, datapath):
+    """
+    Returns the path (as `str`) to the `flatten_doc.xsl` example file.
+
+    Examples
+    --------
+    >>> def test_read_xsl(xsl_flatten_doc):
+    ...     with open(
+    ...         xsl_flatten_doc, mode, encoding="utf-8" if mode == "r" else None
+    ...     ) as f:
+    ...         xsl_obj = f.read()
+    """
     return datapath(xml_data_path / "flatten_doc.xsl")
 
 
 @pytest.fixture
 def xsl_row_field_output(xml_data_path, datapath):
+    """
+    Returns the path (as `str`) to the `row_field_output.xsl` example file.
+
+    Examples
+    --------
+    >>> def test_read_xsl(xsl_row_field_output):
+    ...     with open(
+    ...         xsl_row_field_output, mode, encoding="utf-8" if mode == "r" else None
+    ...     ) as f:
+    ...         xsl_obj = f.read()
+    """
     return datapath(xml_data_path / "row_field_output.xsl")

pandas/tests/util/conftest.py

@@ -3,24 +3,44 @@
 
 @pytest.fixture(params=[True, False])
 def check_dtype(request):
+    """
+    Fixture returning `True` or `False`, determining whether to check
+    if the `dtype` is identical or not, when comparing two data structures,
+    e.g. `Series`, `SparseArray` or `DataFrame`.
+    """
     return request.param
 
 
 @pytest.fixture(params=[True, False])
 def check_exact(request):
+    """
+    Fixture returning `True` or `False`, determining whether to
+    compare floating point numbers exactly or not.
+    """
     return request.param
 
 
 @pytest.fixture(params=[True, False])
 def check_index_type(request):
+    """
+    Fixture returning `True` or `False`, determining whether to check
+    if the `Index` types are identical or not.
+    """
     return request.param
 
 
 @pytest.fixture(params=[0.5e-3, 0.5e-5])
 def rtol(request):
+    """
+    Fixture returning 0.5e-3 or 0.5e-5. Those values are used as relative tolerance.
+    """
     return request.param
 
 
 @pytest.fixture(params=[True, False])
 def check_categorical(request):
+    """
+    Fixture returning `True` or `False`, determining whether to
+    compare internal `Categorical` exactly or not.
+    """
     return request.param