search

audeering / audbcards

Data cards for audio datasets
https://audeering.github.io/audbcards/
Other
0 stars 0 forks source link

DOC: add API documentation #65

Closed hagenw closed 4 months ago

hagenw commented 4 months ago

This adds API documentation for audbcards.Dataset and audbcards.Datacard to the documentation. It sounds like a good idea to me, to add this before we do our first release.

image

hagenw commented 4 months ago
  • When creating from a new venv, I find that the requirement dohq-artifactory is missing and needs to be added using a pip install. For me, it would be ok to add this change here, but as well it would be ok to create a follow-up issue that should be processed pre-release.

This should not happen. audb is a dependency of audbcards, and has dohq-artifactory as dependency, see https://github.com/audeering/audb/blob/916c4e9c538b6b8f376835a2e59be46213d1f4aa/pyproject.toml#L36 and https://github.com/audeering/audbackend/blob/84b723c70bd92ddb4f05a97dc974397d07131d1c/pyproject.toml#L39

  • There is an asymmetry in how the API docs of Dataset and Datacard show up. While for Datacard, properties are rendered, this is not the case for Dataset as its only purpose is to delegate object instantiation to its private counterpart _Dataset. In a follow up one should probably expose Dataset properties and make these accessible to the documentation as this is likely to be of interest to the user.

Good point. As this is more complicated, I created https://github.com/audeering/audbcards/issues/66 to track it.

  • docstring file_duration_distribution: would Min/max not require a period here to flag it as an abbrev.? I.e. Min -> Min. ?

I changed the docstring to

image

  • The Datacard.player docstring for the file parameter: I am not sure whether I understand.

The player needs a file name as input. This is usually hidden from the user when a datacard is used as we automatically use audbcards.Datacard.example_media. That's t he reason why I added the audbcards.Datacard.example_media is a good fit part to the docstring for the file argument. Should I remove the line or rephrase it?

ChristianGeng commented 4 months ago

The player needs a file name as input. This is usually hidden from the user when a datacard is used as we automatically use audbcards.Datacard.example_media. That's t he reason why I added the audbcards.Datacard.example_media is a good fit part to the docstring for the file argument. Should I remove the line or rephrase it?

Now I see. You want to say that the value of audbcards.Datacard.example_media is very likely / sure to work if you want to parametrize it. I am not saying that I know the best way to phase it, but if you have a good way to do so it would be great of course. One could also make it default file to None and use audbcards.Datacard.example_media if it is None - so the type would become a union of None and str.

This should not happen. audb is a dependency of audbcards, and has dohq-artifactory as dependency, see https://github.com/audeering/audb/blob/916c4e9c538b6b8f376835a2e59be46213d1f4aa/pyproject.toml#L36 and https://github.com/audeering/audbackend/blob/84b723c70bd92ddb4f05a97dc974397d07131d1c/pyproject.toml#L39

I have used a python3.9 venv (3.10 working on a compute machine with only 18.04 installed has become less viable since deadsnakes has removed all support for 18.04). Possibly dependencies to not go down well with 3.9 and audb any more. So you can see this as resolved.

So if you want to rephrase the good fit bit this is good to go (and merge it), if not you can also go ahead and merge.

hagenw commented 4 months ago

Good idea, I set the default value of file to None in audbcards.Datacard.player().

image

I will now continue here and merge, thanks for the review.

When I start from an empty environment, created with virtualenv and Python 3.9 and run pip install -r requirements.txt in the root of this repo, it installs the following packages, including dohq-artifactory:

Installed packages ``` audb==1.6.4 audbackend==1.0.2 -e git+ssh://git@github.com/audeering/audbcards.git@db202dc245d5f64a65e0eccba0d489b35bb481ab#egg=audbcards audeer==2.0.0 audformat==1.1.2 audiofile==1.4.0 audmath==1.4.0 audmetric==1.2.0 audobject==0.7.11 audplot==1.4.6 audresample==1.3.3 certifi==2024.2.2 cffi==1.16.0 charset-normalizer==3.3.2 contourpy==1.2.0 cycler==0.12.1 dohq-artifactory==0.10.0 filelock==3.13.1 fonttools==4.49.0 idna==3.6 importlib-metadata==7.0.1 importlib_resources==6.1.2 iso-639==0.4.5 iso3166==2.1.1 Jinja2==3.1.3 kiwisolver==1.4.5 MarkupSafe==2.1.5 matplotlib==3.8.3 numpy==1.26.4 oyaml==1.0 packaging==23.2 pandas==2.2.1 pillow==10.2.0 pycparser==2.21 PyJWT==2.8.0 pyparsing==3.1.1 python-dateutil==2.8.2 pytz==2024.1 PyYAML==6.0.1 requests==2.31.0 seaborn==0.13.2 six==1.16.0 soundfile==0.12.1 toml==0.10.2 tqdm==4.66.2 tzdata==2024.1 urllib3==2.2.1 zipp==3.17.0 ```