Docs details

[severo]

Some comments here:

• the code samples assume the expected libraries have already been installed. Maybe add a section at start, or add it to every code sample. Something like pip install datasets transformers torch 'datasets[streaming]' (maybe just link to https://huggingface.co/docs/datasets/installation.html + a one-liner that installs all the requirements / alternatively a requirements.txt file)
• "If you’d like to play with the examples, you must install it from source." in https://huggingface.co/docs/datasets/installation.html: it's not clear to me what this means (what are these "examples"?)
• in https://huggingface.co/docs/datasets/loading_datasets.html: "or AWS bucket if it’s not already stored in the library". It's the only place in the doc (aside from the docstring https://huggingface.co/docs/datasets/package_reference/loading_methods.html?highlight=aws bucket#datasets.list_datasets) where the "AWS bucket" is mentioned. It's not easy to understand what this means. Maybe explain more, and link to https://s3.amazonaws.com/datasets.huggingface.co and/or https://huggingface.co/docs/datasets/filesystems.html.
• example in https://huggingface.co/docs/datasets/loading_datasets.html#manually-downloading-files is obsoleted by Enable auto-download for PAN-X / Wikiann domain in XTREME #2326. Also: see xtreme / pan-x cannot be downloaded #2691 for a bug on this specific dataset.
• in https://huggingface.co/docs/datasets/loading_datasets.html#manually-downloading-files the doc says "After you’ve downloaded the files, you can point to the folder hosting them locally with the data_dir argument as follows:", but the following example does not show how to use data_dir
• in https://huggingface.co/docs/datasets/loading_datasets.html#csv-files, it would be nice to have an URL to the csv loader reference (but I'm not sure there is one in the API reference). This comment applies in many places in the doc: I would want the API reference to contain doc for all the code/functions/classes... and I would want a lot more links inside the doc pointing to the API entries.
• in the API reference (docstrings) I would prefer "SOURCE" to link to github instead of a copy of the code inside the docs site (eg. https://github.com/huggingface/datasets/blob/master/src/datasets/load.py#L711 instead of https://huggingface.co/docs/datasets/_modules/datasets/load.html#load_dataset)
• it seems like not all the API is exposed in the doc. For example, there is no doc for disable_progress_bar, see https://huggingface.co/docs/datasets/search.html?q=disable_progress_bar, even if the code contains docstrings. Does it mean that the function is not officially supported? (otherwise, maybe it also deserves a mention in https://huggingface.co/docs/datasets/package_reference/logging_methods.html)
• in https://huggingface.co/docs/datasets/loading_datasets.html?highlight=most%20efficient%20format%20have%20json%20files%20consisting%20multiple%20json%20objects#json-files, "The most efficient format is to have JSON files consisting of multiple JSON objects, one per line, representing individual data rows:", maybe link to https://en.wikipedia.org/wiki/JSON_streaming#Line-delimited_JSON and give it a name ("line-delimited JSON"? "JSON Lines" as in https://huggingface.co/docs/datasets/processing.html#exporting-a-dataset-to-csv-json-parquet-or-to-python-objects ?)
• in https://huggingface.co/docs/datasets/loading_datasets.html, for the local files sections, it would be nice to provide sample csv / json / text files to download, so that it's easier for the reader to try to load them (instead: they won't try)
• the doc explains how to shard a dataset, but does not explain why and when a dataset should be sharded (I have no idea... for parallelizing?). It does neither give an idea of the number of shards a dataset typically should have and why.
• the code example in https://huggingface.co/docs/datasets/processing.html#mapping-in-a-distributed-setting does not work, because training_args has not been defined before in the doc.

[lhoestq]

Thanks for all the comments and for the corrections in the docs !

About all the points you mentioned:

• the code samples assume the expected libraries have already been installed. Maybe add a section at start, or add it to every code sample. Something like pip install datasets transformers torch 'datasets[streaming]' (maybe just link to https://huggingface.co/docs/datasets/installation.html + a one-liner that installs all the requirements / alternatively a requirements.txt file)

Yes good idea

• "If you’d like to play with the examples, you must install it from source." in https://huggingface.co/docs/datasets/installation.html: it's not clear to me what this means (what are these "examples"?)

It refers to examples scripts inside the git repository of the library, see the examples folder in the transformers repo.
We don't have examples yet in the git repo of datasets as in transformers. So currently there are no examples. Maybe we can just remove this sentence from the docs for now

• in https://huggingface.co/docs/datasets/loading_datasets.html: "or AWS bucket if it’s not already stored in the library". It's the only place in the doc (aside from the docstring https://huggingface.co/docs/datasets/package_reference/loading_methods.html?highlight=aws bucket#datasets.list_datasets) where the "AWS bucket" is mentioned. It's not easy to understand what this means. Maybe explain more, and link to https://s3.amazonaws.com/datasets.huggingface.co and/or https://huggingface.co/docs/datasets/filesystems.html.

This is outdated and must be replaced by

or from the Hugging Face Hub if it’s not already stored in the library

• example in https://huggingface.co/docs/datasets/loading_datasets.html#manually-downloading-files is obsoleted by Enable auto-download for PAN-X / Wikiann domain in XTREME #2326. Also: see xtreme / pan-x cannot be downloaded #2691 for a bug on this specific dataset.

We can replace the XTREME PANX dataste by matinf instead for example

• in https://huggingface.co/docs/datasets/loading_datasets.html#manually-downloading-files the doc says "After you’ve downloaded the files, you can point to the folder hosting them locally with the data_dir argument as follows:", but the following example does not show how to use data_dir

Let's add data_dir="path/to/your/downloaded/data" for example

• in https://huggingface.co/docs/datasets/loading_datasets.html#csv-files, it would be nice to have an URL to the csv loader reference (but I'm not sure there is one in the API reference). This comment applies in many places in the doc: I would want the API reference to contain doc for all the code/functions/classes... and I would want a lot more links inside the doc pointing to the API entries.

Currently there's no documentation for the CSV loader config. Maybe we can add the docstrings to the CsvConfig class to explain the parameters and how it works, and then redirect to the doc of this class in this section of the documentation.

• in the API reference (docstrings) I would prefer "SOURCE" to link to github instead of a copy of the code inside the docs site (eg. https://github.com/huggingface/datasets/blob/master/src/datasets/load.py#L711 instead of https://huggingface.co/docs/datasets/_modules/datasets/load.html#load_dataset)

This is the same as in transformers, not sure if this is a big issue

• it seems like not all the API is exposed in the doc. For example, there is no doc for disable_progress_bar, see https://huggingface.co/docs/datasets/search.html?q=disable_progress_bar, even if the code contains docstrings. Does it mean that the function is not officially supported? (otherwise, maybe it also deserves a mention in https://huggingface.co/docs/datasets/package_reference/logging_methods.html)

The function disable_progress_bar should definitely be in the docs, thanks. We can add it to the logging methods

• in https://huggingface.co/docs/datasets/loading_datasets.html?highlight=most%20efficient%20format%20have%20json%20files%20consisting%20multiple%20json%20objects#json-files, "The most efficient format is to have JSON files consisting of multiple JSON objects, one per line, representing individual data rows:", maybe link to https://en.wikipedia.org/wiki/JSON_streaming#Line-delimited_JSON and give it a name ("line-delimited JSON"? "JSON Lines" as in https://huggingface.co/docs/datasets/processing.html#exporting-a-dataset-to-csv-json-parquet-or-to-python-objects ?)

Yes good idea !

• in https://huggingface.co/docs/datasets/loading_datasets.html, for the local files sections, it would be nice to provide sample csv / json / text files to download, so that it's easier for the reader to try to load them (instead: they won't try)

Sure why not. Moreover the csv loader now supports remote files so you could just run the code pass an an URL to the sample csv file.

• the doc explains how to shard a dataset, but does not explain why and when a dataset should be sharded (I have no idea... for parallelizing?). It does neither give an idea of the number of shards a dataset typically should have and why.

This can be used for distributed processing or just to use a percentage of the data. We can definitely give example of use cases

• the code example in https://huggingface.co/docs/datasets/processing.html#mapping-in-a-distributed-setting does not work, because training_args has not been defined before in the doc.

training_args comes from transformers, it's a practical way to define all your arguments to train a model. Maybe we can just import it from transformers and use it with the default values

[lhoestq]

Thanks for the corrections.
Though not all your comments have been addressed in this PR, we can already merge it.
As you may know we'll have a new documentation soon anyway ;)