Add table preview to data cards

[hagenw]

Closes #59

Adds a table preview to audbcards.

audbcards.Dataset.tables_preview

The pull request adds the cached property audbcards.Dataset.tables_preview which returns a dictionary with table IDs as keys and a list of table rows as values.
It downloads the whole table to create a preview. We might improve on this later on as described in #100.

Having #101 in mind, this pull request adds an usage example to the docstring of audbcards.Dataset.tables_preview and uses doctest to check its correctness.

Integration in audbcards.Datacard

The pull request updates the datacard_tables.j2 template to integrate the table preview in the existing tables table. The rows of the tables table are now clickable and show the preview table below the clicked row.

Theme compatibility

When introducing new CSS based features, one has to ensure that they don't contain theme specific CSS code.

I tested it with the standard sphinx alabaster theme:

With inspid theme (requires another virtual environment with newer sphinx and docutils):

With sphinx-audeering-theme:

Theme update

I further created already a pull request for sphinx-audeering-theme, that adds some custom styling to the new table preview (which was used in the animated gif above): audeering/sphinx-audeering-theme#84.
Applying the update to the theme will result in

Ensure text in table preview is valid

As we include table content as string in an HTML table, not all characters are allowed. E.g. from our existing datasets era-dialog would result in an error, if the text is not adjusted. This pull request adds audbcards.core.utils.parse_text() to remove HTML characters, replace newline with "\\n" and limit the length of the text to 100 characters.

[ChristianGeng]

I am experiencing a red test: test_datacard_player fails in its last line at assert waveform == expected_waveform.
Going through the test I am having difficulty to understand why this is the case.

        plt.close()
        expected_waveform = open(outfile, "rb").read()
        # Check if generated images are exactly the same (pixel-wise)
        waveform = open(image_file, "rb").read()
>       assert waveform == expected_waveform
E       AssertionError: assert b'\x89PNG\r\n...END\xaeB`\x82' == b'\x89PNG\r\n...END\xaeB`\x82'
E         
E         At index 70 diff: b'8' != b'9'
E         
E         Full diff:
E           (b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x01,\x00\x00\x002'
E            b'\x08\x06\x00\x00\x00\xe6\xd6\xe6*\x00\x00\x009tEXtSoftware\x00Matplotlib ver'
E         -  b'sion3.9.1, https://matplotlib.org/\xd3\x19\xee!\x00\x00\x00\tpHYs\x00\x00'...
E         
E         ...Full output truncated (290 lines hidden), use '-vv' to show

tests/test_datacard.py:212: AssertionError

[hagenw]

As we cannot reproduce it with the CI job, my guess is that it is cache related.

We handle the following cache folders:

• audb cache handled by

  audbcards/tests/conftest.py

  Lines 31 to 36 in bb3820b

  	@pytest.fixture
  	def audb_cache(tmpdir, scope="session", autouse=True):
  	"""Local audb cache folder."""
  	cache = audeer.mkdir(audeer.path(tmpdir, "audb-cache"))
  	audb.config.CACHE_ROOT = cache
  	audb.config.SHARED_CACHE_ROOT = cache

• audbcards.Dataset cache handled by

  audbcards/tests/test_datacard.py

  Line 128 in bb3820b

  dataset = audbcards.Dataset(db.name, pytest.VERSION, cache_root=cache)

  and the cache fixture defined in

  audbcards/tests/conftest.py

  Lines 25 to 28 in bb3820b

  	@pytest.fixture
  	def cache(tmpdir, scope="function"):
  	"""Local cache folder."""
  	return audeer.mkdir(audeer.path(tmpdir, "cache"))

But for audbcards.Datacard we do not define the temporary cache in the test:

audbcards/tests/test_datacard.py

Line 131 in bb3820b

datacard = audbcards.Datacard(dataset, path=datacard_path)

Can you maybe delete (or temporary move to another place) your audbcards cache folder (~/.cache/audbcards) and rerun the test?

[hagenw]

I created #103 to ensure we always use the temporary cache folder when testing audbcards.Datacard.

[ChristianGeng]

I wonder whether there is a reason to put this into the utils module? My understanding would be that this function has a small amout of usecases it can be reasonable applied to - but I could be wrong.
At least I can only image the current Dataset.tables_preview right now. If I am right: would it not make sense to rather let it live in Dataset as a static private method? For testing this would be not more problematic as staticmethods can be addressed without object instantiation.

[hagenw]

You are right, testing was the only reason why added parse_text() to utils. I moved it now to a private static method of Dataset.

[ChristianGeng]

if I had to develop such a feature myself, the only aspect I found off-putting would have been that the jinja becomes quite acrobatic.

I have tested this functionally:

I can recreate the documentation with the audeering theme and also alabaster.

Aesthetically this is a nice feature to have. In case of problems the preview will simply stop working, and the users will not be affected.

Therefore I will rush to approve it.