TST: enable tests for documentation files (#478)

* TST: enable tests for documentation files

* Fix sorting of file listing

* Use context manager for setting default values

* Fix sorting of os.walk

* Fix order in conftest.py

* Skip test for pandas == 2.1.4

* Fix typo

* fix cache test under MacOS, skip under Windows

* Fix typo

* Fix skipping of tests for caching

* Fix path in quickstart under Windows

* Remove unneeded import

docs/caching.rst

@@ -1,5 +1,12 @@
 .. _caching:
 
+.. As the test outputs are mainly paths,
+.. we skip the tests under Windows
+..
+   >>> import platform
+
+.. skip: start if(platform.system() == "Windows")
+
 Caching
 =======
 
@@ -44,7 +51,7 @@ accessible to you only.
 By default it points to
 
 >>> audb.default_cache_root(shared=False)
-'/home/.../audb'
+'.../audb'
 
 When you request a database with :meth:`audb.load`,
 :mod:`audb` first looks for it in the shared cache folder
@@ -58,6 +65,7 @@ There are four ways to change the default locations:
 
 1. By setting the argument ``cache_root`` during a function call, e.g.
 
+.. skip: end
 .. skip: next
 
 >>> db = audb.load("emodb", ..., cache_root="/cache/root/audb")
@@ -71,6 +79,8 @@ There are four ways to change the default locations:
 
 3. Program-wide by overwriting the default values in :class:`audb.config`
 
+.. skip: start if(platform.system() == "Windows")
+
 >>> audb.config.SHARED_CACHE_ROOT = "/new/shared/cache/audb"
 >>> audb.default_cache_root(shared=True)
 '/new/shared/cache/audb'
@@ -88,5 +98,6 @@ Note,
 2. overwrites 3. and 4.,
 and so on.
 
+.. skip: end
 
 .. _adjust the rights: https://superuser.com/a/264406

docs/conftest.py

@@ -0,0 +1,108 @@
+from doctest import ELLIPSIS
+from doctest import NORMALIZE_WHITESPACE
+import os
+
+import pytest
+import sybil
+from sybil.parsers.rest import DocTestParser
+from sybil.parsers.rest import PythonCodeBlockParser
+from sybil.parsers.rest import SkipParser
+
+import audb
+from audb.core.conftest import cache  # noqa: F401
+from audb.core.conftest import imports
+from audb.core.conftest import public_repository  # noqa: F401
+
+
+class DefaultConfiguration:
+    """Context manager to provide default configuration values."""
+
+    def __init__(self):
+        self.config = audb.core.config.load_configuration_file(
+            audb.core.config.global_config_file
+        )
+        self._saved_state = {}
+
+    def __enter__(self):
+        """Save current state."""
+        self._saved_state = {
+            "cache_root": audb.config.CACHE_ROOT,
+            "shared_cache_root": audb.config.SHARED_CACHE_ROOT,
+            "repositories": audb.config.REPOSITORIES,
+        }
+        # Set default values
+        audb.config.CACHE_ROOT = self.config["cache_root"]
+        audb.config.SHARED_CACHE_ROOT = self.config["shared_cache_root"]
+        audb.config.REPOSITORIES = [
+            audb.Repository(repo["name"], repo["host"], repo["backend"])
+            for repo in self.config["repositories"]
+        ]
+
+    def __exit__(self, *args):
+        """Restore previous state."""
+        for key, value in self._saved_state.items():
+            setattr(audb.config, key, value)
+
+
+@pytest.fixture(scope="module")
+def default_configuration():
+    """Set config values to default values."""
+    with DefaultConfiguration():
+        yield
+
+
+@pytest.fixture(scope="module")
+def run_in_tmpdir(tmpdir_factory):
+    """Move to a persistent tmpdir for execution of a whole file."""
+    tmpdir = tmpdir_factory.mktemp("tmp")
+    current_dir = os.getcwd()
+    os.chdir(tmpdir)
+
+    yield
+
+    os.chdir(current_dir)
+
+
+# Collect doctests
+#
+# We use several `sybil.Sybil` instances
+# to pass different fixtures for different files
+#
+parsers = [
+    DocTestParser(optionflags=ELLIPSIS + NORMALIZE_WHITESPACE),
+    PythonCodeBlockParser(),
+    SkipParser(),
+]
+pytest_collect_file = sybil.sybil.SybilCollection(
+    (
+        sybil.Sybil(
+            parsers=parsers,
+            filenames=[
+                "authentication.rst",
+                "overview.rst",
+                "quickstart.rst",
+                "dependencies.rst",
+                "load.rst",
+                "audb.info.rst",
+            ],
+            fixtures=[
+                "cache",
+                "run_in_tmpdir",
+                "public_repository",
+            ],
+            setup=imports,
+        ),
+        sybil.Sybil(
+            parsers=parsers,
+            filenames=["publish.rst"],
+            fixtures=["cache", "run_in_tmpdir"],
+            setup=imports,
+        ),
+        sybil.Sybil(
+            parsers=parsers,
+            filenames=["configuration.rst", "caching.rst"],
+            fixtures=["default_configuration"],
+            setup=imports,
+        ),
+    )
+).pytest()

docs/dependencies.rst

@@ -48,6 +48,11 @@ If your database contains only WAV or FLAC files,
 we store the duration in seconds of every file
 in the database dependency table.
 
+..
+    >>> import pandas as pd
+
+.. skip: start if(pd.__version__ == "2.1.4", reason="formats output differently")
+
 >>> deps = audb.dependencies("emodb", version="1.4.1")
 >>> df = deps()
 >>> df.duration[:10]
@@ -63,6 +68,8 @@ wav/03a02Wb.wav    2.123625
 wav/03a02Wc.wav    1.498063
 Name: duration, dtype: double[pyarrow]
 
+.. skip: end
+
 For those databases
 you can get their overall duration with:
 

docs/publish.rst

@@ -113,12 +113,12 @@ We can compare this with the files stored in the repository.
     import os
 
     def list_files(path):
-        for root, dirs, files in os.walk(path):
+        for root, _, files in sorted(os.walk(path)):
             level = root.replace(path, "").count(os.sep)
             indent = " " * 2 * (level)
             print(f"{indent}{os.path.basename(root)}/")
             subindent = " " * 2 * (level + 1)
-            for f in files:
+            for f in sorted(files):
                 print(f"{subindent}{f}")
 
 >>> list_files(repository.host)
@@ -128,14 +128,14 @@ data/
       1.0.0/
         db.parquet
         db.yaml
-      meta/
-        1.0.0/
-          age.parquet
       media/
         1.0.0/
-          e26ef45d-bdc1-6153-bdc4-852d83806e4a.zip
           436c65ec-1e42-f9de-2708-ecafe07e827e.zip
+          e26ef45d-bdc1-6153-bdc4-852d83806e4a.zip
           fda7e4d6-f2b2-4cff-cab5-906ef5d57607.zip
+      meta/
+        1.0.0/
+          age.parquet
 
 As you can see all media files are stored
 inside the ``media/`` folder,
@@ -246,24 +246,24 @@ We can again inspect the repository.
 data/
   data-local/
     age-test/
-      1.1.0/
+      1.0.0/
         db.parquet
         db.yaml
-      1.0.0/
+      1.1.0/
         db.parquet
         db.yaml
-      meta/
-        1.1.0/
-          age.parquet
-        1.0.0/
-          age.parquet
       media/
-        1.1.0/
-          ef4d1e81-6488-95cf-a165-604d1e47d575.zip
         1.0.0/
-          e26ef45d-bdc1-6153-bdc4-852d83806e4a.zip
           436c65ec-1e42-f9de-2708-ecafe07e827e.zip
+          e26ef45d-bdc1-6153-bdc4-852d83806e4a.zip
           fda7e4d6-f2b2-4cff-cab5-906ef5d57607.zip
+        1.1.0/
+          ef4d1e81-6488-95cf-a165-604d1e47d575.zip
+      meta/
+        1.0.0/
+          age.parquet
+        1.1.0/
+          age.parquet
 
 And check which databases are available.
 

docs/quickstart.rst

@@ -22,8 +22,6 @@ Let's load version 1.4.1 of the emodb_ database.
 .. Load with only_metadata=True in the background
 .. invisible-code-block: python
 
-    import audformat as _audformat
-
     db = audb.load(
         "emodb",
         version="1.4.1",
@@ -32,11 +30,9 @@ Let's load version 1.4.1 of the emodb_ database.
         verbose=False,
     )
     # Add flavor path, to mimic `full_path=True`
+    flavor_path = audb.flavor_path("emodb", "1.4.1").replace("\\", "/")
     for table in list(db.tables):
-        db[table]._df.index = _audformat.utils.expand_file_path(
-            db[table]._df.index,
-            f'...{audb.flavor_path("emodb", "1.4.1")}',
-        )
+        db[table]._df.index = f"...{flavor_path}/" + db[table]._df.index
 
 .. skip: next