Add Datacard.segment_duration_distribution

[hagenw]

Makes use of audbcards.Dataset.segments and audbcards.Dataset.segment_durations, introduced in #31 to add audbcards.Datacard.segment_duration_distribution.

API documentation

Example dataset page

[ChristianGeng]

In order to produce a review for this issue, I have limited myself to building the documentation. The code builds flawlessly. I can render the documentation, and indeed, the public datasets contain a database that has segments - vadtoolkit which is pleasant to work with. For now I see this enough as a functional check.

There are two minor things that made me wonder:

1. convention of html-build location

I ususally expect locally built documentation in build/html/. For this project it deviates and is now at build/sphinx/html/. Have the conventions changed?
Or is this a one off?

2. Check of produced documentation file paths - sphinx-src-dir

• the location of segment distribution files in cache pans out: /.cache/audbcards/vadtoolkit/1.1.0/vadtoolkit-1.1.0-segment-duration-distribution.png foolows the filename convention in the documentation, and the location in <cache-root>/<dataset-name>/<dataset-version>/ is also correct.

• the location of the image file in sphinx-src- dir I find more difficulat. Within sphinx-src-dir I have this file: ~/work/tools-public/audbcards/build/sphinx/html/_images/vadtoolkit-1.1.0-segment-duration-distribution.png.
  What would the variables in <sphinx-src-dir>/<path><dataset-name>/ need to be expanded to in order to get this valid?

[hagenw]

1. convention of html-build location

You are correct, if asked I would recommend the following command to build the docs:

$ python -m sphinx docs/ build/html -b html

I think the old build/sphinx/html that is mentioned in CONTRIBUTING.rst stems from an earlier version, that we siomply copy and pasted from other projects, e.g. in audb it is also present.

I created #102 to change this for audbcards.

[hagenw]

2. Check of produced documentation file paths - sphinx-src-dir

Within sphinx-src-dir I have this file: ~/work/tools-public/audbcards/build/sphinx/html/_images/vadtoolkit-1.1.0-segment-duration-distribution.png.
What would the variables in `//`` need to be expanded to in order to get this valid?

What do you mean by the last sentence?

[ChristianGeng]

2. Check of produced documentation file paths - sphinx-src-dir

Within sphinx-src-dir I have this file: ~/work/tools-public/audbcards/build/sphinx/html/_images/vadtoolkit-1.1.0-segment-duration-distribution.png.
What would the variables in `//`` need to be expanded to in order to get this valid?

What do you mean by the last sentence?

This was a backtick error:
<sphinx-src-dir>/<path><dataset-name>/ was intended between //

[hagenw]

2. Check of produced documentation file paths - sphinx-src-dir

We start from cache at the position you located correctly: ~/.cache/audbcards/vadtoolkit/1.1.0/vadtoolkit-1.1.0-segment-duration-distribution.png. Then we copy the file into the documentation source folder with

audbcards/audbcards/core/datacard.py

Lines 402 to 409 in f871fa1

	image_file = audeer.path(
	self.sphinx_src_dir,
	self.path,
	self.dataset.name,
	file_name,
	)
	audeer.mkdir(os.path.dirname(image_file))
	shutil.copyfile(cache_file, image_file)

Which means it will be located at ./docs/data-public/vadtoolkit/vadtoolkit-1.1.0-segment-duration-distribution.png, whereby data-public is given by the audbcards_datasets entry in docs/conf.py.

sphinx will then copy the file to the build/html/_images folder when building the documentation, and sets the links in the resulting HTML pages accordingly (this is the default sphinx behavior, we do not force it to do this). At the end, sphinx will also clean up the docs/ folder by deleting all files it has created in between:

audbcards/audbcards/sphinx/__init__.py

Lines 133 to 141 in f871fa1

	# Delete auto-generated data card output folder
	sections = app.config.audbcards_datasets
	for path, _, _, _ in sections:
	datacard_path = audeer.path(app.srcdir, path)
	audeer.rmdir(datacard_path)
	for ext in ["rst", "csv"]:
	file = audeer.path(app.srcdir, f"{path}.{ext}")
	if os.path.exists(file):
	os.remove(file)

This means, you will not find ./docs/data-public/vadtoolkit/vadtoolkit-1.1.0-segment-duration-distribution.png.