Update doc

PiperOrigin-RevId: 252109635

Author: Conchylicultor

docs/api_docs/python/_toc.yaml

@@ -32,6 +32,8 @@ toc:
       path: /datasets/api_docs/python/tfds/core/DatasetBuilder
     - title: DatasetInfo
       path: /datasets/api_docs/python/tfds/core/DatasetInfo
+    - title: Experiment
+      path: /datasets/api_docs/python/tfds/core/Experiment
     - title: GeneratorBasedBuilder
       path: /datasets/api_docs/python/tfds/core/GeneratorBasedBuilder
     - title: get_tfds_path

docs/api_docs/python/index.md

@@ -10,6 +10,7 @@
 *   <a href="./tfds/core/BuilderConfig.md"><code>tfds.core.BuilderConfig</code></a>
 *   <a href="./tfds/core/DatasetBuilder.md"><code>tfds.core.DatasetBuilder</code></a>
 *   <a href="./tfds/core/DatasetInfo.md"><code>tfds.core.DatasetInfo</code></a>
+*   <a href="./tfds/core/Experiment.md"><code>tfds.core.Experiment</code></a>
 *   <a href="./tfds/core/GeneratorBasedBuilder.md"><code>tfds.core.GeneratorBasedBuilder</code></a>
 *   <a href="./tfds/core/Metadata.md"><code>tfds.core.Metadata</code></a>
 *   <a href="./tfds/core/MetadataDict.md"><code>tfds.core.MetadataDict</code></a>

docs/api_docs/python/tfds/_api_cache.json

@@ -10,11 +10,13 @@
     "tfds.core.BeamBasedBuilder.builder_config": "tfds.core.DatasetBuilder.builder_config", 
     "tfds.core.BeamBasedBuilder.data_dir": "tfds.core.DatasetBuilder.data_dir", 
     "tfds.core.BeamBasedBuilder.info": "tfds.core.DatasetBuilder.info", 
+    "tfds.core.BeamBasedBuilder.version": "tfds.core.DatasetBuilder.version", 
     "tfds.core.GeneratorBasedBuilder.BUILDER_CONFIGS": "tfds.core.DatasetBuilder.BUILDER_CONFIGS", 
     "tfds.core.GeneratorBasedBuilder.SUPPORTED_VERSIONS": "tfds.core.DatasetBuilder.SUPPORTED_VERSIONS", 
     "tfds.core.GeneratorBasedBuilder.builder_config": "tfds.core.DatasetBuilder.builder_config", 
     "tfds.core.GeneratorBasedBuilder.data_dir": "tfds.core.DatasetBuilder.data_dir", 
     "tfds.core.GeneratorBasedBuilder.info": "tfds.core.DatasetBuilder.info", 
+    "tfds.core.GeneratorBasedBuilder.version": "tfds.core.DatasetBuilder.version", 
     "tfds.core.MetadataDict.__contains__": "tfds.core.Metadata.__contains__", 
     "tfds.core.MetadataDict.__eq__": "tfds.core.Metadata.__eq__", 
     "tfds.core.MetadataDict.__ge__": "tfds.core.Metadata.__ge__", 
@@ -67,25 +69,9 @@
     "tfds.core.SplitDict.viewitems": "tfds.core.Metadata.viewitems", 
     "tfds.core.SplitDict.viewkeys": "tfds.core.Metadata.viewkeys", 
     "tfds.core.SplitDict.viewvalues": "tfds.core.Metadata.viewvalues", 
-    "tfds.core.Version.__init__": "tfds.core.SplitBase.__init__", 
     "tfds.features.Audio.dtype": "tfds.features.FeatureConnector.dtype", 
     "tfds.features.Audio.shape": "tfds.features.FeatureConnector.shape", 
-    "tfds.features.BBox.__add__": "tfds.core.Version.__add__", 
-    "tfds.features.BBox.__contains__": "tfds.core.Version.__contains__", 
-    "tfds.features.BBox.__eq__": "tfds.core.Version.__eq__", 
-    "tfds.features.BBox.__ge__": "tfds.core.Version.__ge__", 
-    "tfds.features.BBox.__getitem__": "tfds.core.Version.__getitem__", 
-    "tfds.features.BBox.__gt__": "tfds.core.Version.__gt__", 
     "tfds.features.BBox.__init__": "tfds.core.SplitBase.__init__", 
-    "tfds.features.BBox.__iter__": "tfds.core.Version.__iter__", 
-    "tfds.features.BBox.__le__": "tfds.core.Version.__le__", 
-    "tfds.features.BBox.__len__": "tfds.core.Version.__len__", 
-    "tfds.features.BBox.__lt__": "tfds.core.Version.__lt__", 
-    "tfds.features.BBox.__mul__": "tfds.core.Version.__mul__", 
-    "tfds.features.BBox.__ne__": "tfds.core.Version.__ne__", 
-    "tfds.features.BBox.__rmul__": "tfds.core.Version.__rmul__", 
-    "tfds.features.BBox.count": "tfds.core.Version.count", 
-    "tfds.features.BBox.index": "tfds.core.Version.index", 
     "tfds.features.BBoxFeature.dtype": "tfds.features.FeatureConnector.dtype", 
     "tfds.features.BBoxFeature.shape": "tfds.features.FeatureConnector.shape", 
     "tfds.features.ClassLabel.dtype": "tfds.features.FeatureConnector.dtype", 
@@ -110,11 +96,13 @@
     "tfds.testing.DummyDatasetSharedGenerator.builder_config": "tfds.core.DatasetBuilder.builder_config", 
     "tfds.testing.DummyDatasetSharedGenerator.data_dir": "tfds.core.DatasetBuilder.data_dir", 
     "tfds.testing.DummyDatasetSharedGenerator.info": "tfds.core.DatasetBuilder.info", 
+    "tfds.testing.DummyDatasetSharedGenerator.version": "tfds.core.DatasetBuilder.version", 
     "tfds.testing.DummyMnist.BUILDER_CONFIGS": "tfds.core.DatasetBuilder.BUILDER_CONFIGS", 
     "tfds.testing.DummyMnist.SUPPORTED_VERSIONS": "tfds.core.DatasetBuilder.SUPPORTED_VERSIONS", 
     "tfds.testing.DummyMnist.builder_config": "tfds.core.DatasetBuilder.builder_config", 
     "tfds.testing.DummyMnist.data_dir": "tfds.core.DatasetBuilder.data_dir", 
     "tfds.testing.DummyMnist.info": "tfds.core.DatasetBuilder.info", 
+    "tfds.testing.DummyMnist.version": "tfds.core.DatasetBuilder.version", 
     "tfds.testing.FeatureExpectationsTestCase.failureException": "tfds.testing.DatasetBuilderTestCase.failureException", 
     "tfds.testing.FeatureExpectationsTestCase.failureException.__getitem__": "tfds.testing.DatasetBuilderTestCase.failureException.__getitem__", 
     "tfds.testing.FeatureExpectationsTestCase.failureException.__init__": "tfds.testing.DatasetBuilderTestCase.failureException.__init__", 
@@ -163,6 +151,7 @@
     "tfds.core.BeamBasedBuilder.download_and_prepare": true, 
     "tfds.core.BeamBasedBuilder.info": true, 
     "tfds.core.BeamBasedBuilder.name": true, 
+    "tfds.core.BeamBasedBuilder.version": true, 
     "tfds.core.BuilderConfig": false, 
     "tfds.core.BuilderConfig.__init__": true, 
     "tfds.core.BuilderConfig.description": true, 
@@ -183,6 +172,7 @@
     "tfds.core.DatasetBuilder.download_and_prepare": true, 
     "tfds.core.DatasetBuilder.info": true, 
     "tfds.core.DatasetBuilder.name": true, 
+    "tfds.core.DatasetBuilder.version": true, 
     "tfds.core.DatasetInfo": false, 
     "tfds.core.DatasetInfo.__init__": true, 
     "tfds.core.DatasetInfo.as_json": true, 
@@ -205,6 +195,8 @@
     "tfds.core.DatasetInfo.urls": true, 
     "tfds.core.DatasetInfo.version": true, 
     "tfds.core.DatasetInfo.write_to_directory": true, 
+    "tfds.core.Experiment": false, 
+    "tfds.core.Experiment.DUMMY": true, 
     "tfds.core.GeneratorBasedBuilder": false, 
     "tfds.core.GeneratorBasedBuilder.BUILDER_CONFIGS": true, 
     "tfds.core.GeneratorBasedBuilder.GOOGLE_DISABLED": true, 
@@ -219,6 +211,7 @@
     "tfds.core.GeneratorBasedBuilder.download_and_prepare": true, 
     "tfds.core.GeneratorBasedBuilder.info": true, 
     "tfds.core.GeneratorBasedBuilder.name": true, 
+    "tfds.core.GeneratorBasedBuilder.version": true, 
     "tfds.core.Metadata": false, 
     "tfds.core.Metadata.__contains__": true, 
     "tfds.core.Metadata.__eq__": true, 
@@ -287,12 +280,14 @@
     "tfds.core.NamedSplit.__add__": true, 
     "tfds.core.NamedSplit.__eq__": true, 
     "tfds.core.NamedSplit.__init__": true, 
+    "tfds.core.NamedSplit.__ne__": true, 
     "tfds.core.NamedSplit.get_read_instruction": true, 
     "tfds.core.NamedSplit.subsplit": true, 
     "tfds.core.SplitBase": false, 
     "tfds.core.SplitBase.__add__": true, 
     "tfds.core.SplitBase.__eq__": true, 
     "tfds.core.SplitBase.__init__": true, 
+    "tfds.core.SplitBase.__ne__": true, 
     "tfds.core.SplitBase.get_read_instruction": true, 
     "tfds.core.SplitBase.subsplit": true, 
     "tfds.core.SplitDict": false, 
@@ -337,27 +332,16 @@
     "tfds.core.SplitInfo.get_proto": true, 
     "tfds.core.SplitInfo.num_examples": true, 
     "tfds.core.Version": false, 
-    "tfds.core.Version.LATEST": true, 
-    "tfds.core.Version.__add__": true, 
-    "tfds.core.Version.__contains__": true, 
     "tfds.core.Version.__eq__": true, 
     "tfds.core.Version.__ge__": true, 
-    "tfds.core.Version.__getitem__": true, 
     "tfds.core.Version.__gt__": true, 
     "tfds.core.Version.__init__": true, 
-    "tfds.core.Version.__iter__": true, 
     "tfds.core.Version.__le__": true, 
-    "tfds.core.Version.__len__": true, 
     "tfds.core.Version.__lt__": true, 
-    "tfds.core.Version.__mul__": true, 
     "tfds.core.Version.__ne__": true, 
-    "tfds.core.Version.__rmul__": true, 
-    "tfds.core.Version.count": true, 
-    "tfds.core.Version.index": true, 
-    "tfds.core.Version.major": true, 
+    "tfds.core.Version.implements": true, 
     "tfds.core.Version.match": true, 
-    "tfds.core.Version.minor": true, 
-    "tfds.core.Version.patch": true, 
+    "tfds.core.Version.tuple": true, 
     "tfds.core.get_tfds_path": false, 
     "tfds.core.lazy_imports": false, 
     "tfds.disable_progress_bar": false, 
@@ -601,8 +585,6 @@
     "tfds.file_adapter.TFRecordExampleAdapter.__init__": true, 
     "tfds.file_adapter.TFRecordExampleAdapter.dataset_from_filename": true, 
     "tfds.file_adapter.TFRecordExampleAdapter.filetype_suffix": true, 
-    "tfds.file_adapter.TFRecordExampleAdapter.parse_example": true, 
-    "tfds.file_adapter.TFRecordExampleAdapter.serialize_example": true, 
     "tfds.file_adapter.TFRecordExampleAdapter.write_from_generator": true, 
     "tfds.file_adapter.TFRecordExampleAdapter.write_from_pcollection": true, 
     "tfds.is_dataset_on_gcs": false, 
@@ -773,6 +755,7 @@
     "tfds.testing.DummyDatasetSharedGenerator.download_and_prepare": true, 
     "tfds.testing.DummyDatasetSharedGenerator.info": true, 
     "tfds.testing.DummyDatasetSharedGenerator.name": true, 
+    "tfds.testing.DummyDatasetSharedGenerator.version": true, 
     "tfds.testing.DummyMnist": false, 
     "tfds.testing.DummyMnist.BUILDER_CONFIGS": true, 
     "tfds.testing.DummyMnist.GOOGLE_DISABLED": true, 
@@ -787,6 +770,7 @@
     "tfds.testing.DummyMnist.download_and_prepare": true, 
     "tfds.testing.DummyMnist.info": true, 
     "tfds.testing.DummyMnist.name": true, 
+    "tfds.testing.DummyMnist.version": true, 
     "tfds.testing.FeatureExpectationItem": false, 
     "tfds.testing.FeatureExpectationItem.__init__": true, 
     "tfds.testing.FeatureExpectationsTestCase": false, 

docs/api_docs/python/tfds/core.md

@@ -22,6 +22,9 @@ Defined in [`core/__init__.py`](https://github.com/tensorflow/datasets/tree/mast
 
 [`class DatasetInfo`](../tfds/core/DatasetInfo.md): Information about a dataset.
 
+[`class Experiment`](../tfds/core/Experiment.md): Experiments which can be
+enabled/disabled on a per version basis.
+
 [`class GeneratorBasedBuilder`](../tfds/core/GeneratorBasedBuilder.md): Base class for datasets with data generation based on dict generators.
 
 [`class Metadata`](../tfds/core/Metadata.md): Abstract base class for

docs/api_docs/python/tfds/core/BeamBasedBuilder.md

@@ -4,6 +4,7 @@
 <meta itemprop="property" content="builder_config"/>
 <meta itemprop="property" content="data_dir"/>
 <meta itemprop="property" content="info"/>
+<meta itemprop="property" content="version"/>
 <meta itemprop="property" content="__init__"/>
 <meta itemprop="property" content="as_dataset"/>
 <meta itemprop="property" content="download_and_prepare"/>
@@ -52,7 +53,9 @@ Callers must pass arguments as keyword arguments.
     subdirectories and versions.
 *   <b>`version`</b>: `str`. Optional version at which to load the dataset. An
     error is raised if specified version cannot be satisfied. Eg: '1.2.3',
-    '1.2.*'.
+    '1.2.*'. The special value "experimental_latest" will use the highest
+    version, even if not default. This is not recommended unless you know what
+    you are doing, as the version could be broken.
 
 ## Properties
 
@@ -66,6 +69,8 @@ Callers must pass arguments as keyword arguments.
 
 <a href="../../tfds/core/DatasetInfo.md"><code>tfds.core.DatasetInfo</code></a> for this builder.
 
+<h3 id="version"><code>version</code></h3>
+
 ## Methods
 
 <h3 id="as_dataset"><code>as_dataset</code></h3>

docs/api_docs/python/tfds/core/DatasetBuilder.md

@@ -4,6 +4,7 @@
 <meta itemprop="property" content="builder_config"/>
 <meta itemprop="property" content="data_dir"/>
 <meta itemprop="property" content="info"/>
+<meta itemprop="property" content="version"/>
 <meta itemprop="property" content="__init__"/>
 <meta itemprop="property" content="as_dataset"/>
 <meta itemprop="property" content="download_and_prepare"/>
@@ -83,7 +84,9 @@ Callers must pass arguments as keyword arguments.
     subdirectories and versions.
 *   <b>`version`</b>: `str`. Optional version at which to load the dataset. An
     error is raised if specified version cannot be satisfied. Eg: '1.2.3',
-    '1.2.*'.
+    '1.2.*'. The special value "experimental_latest" will use the highest
+    version, even if not default. This is not recommended unless you know what
+    you are doing, as the version could be broken.
 
 ## Properties
 
@@ -97,6 +100,8 @@ Callers must pass arguments as keyword arguments.
 
 <a href="../../tfds/core/DatasetInfo.md"><code>tfds.core.DatasetInfo</code></a> for this builder.
 
+<h3 id="version"><code>version</code></h3>
+
 ## Methods
 
 <h3 id="as_dataset"><code>as_dataset</code></h3>

docs/api_docs/python/tfds/core/Experiment.md

@@ -0,0 +1,32 @@
+<div itemscope itemtype="http://developers.google.com/ReferenceObject">
+<meta itemprop="name" content="tfds.core.Experiment" />
+<meta itemprop="path" content="Stable" />
+<meta itemprop="property" content="DUMMY"/>
+</div>
+
+# tfds.core.Experiment
+
+## Class `Experiment`
+
+Experiments which can be enabled/disabled on a per version basis.
+
+Defined in
+[`core/utils/version.py`](https://github.com/tensorflow/datasets/tree/master/tensorflow_datasets/core/utils/version.py).
+
+<!-- Placeholder for "Used in" -->
+
+Experiments are designed to gradually apply changes to datasets while
+maintaining backward compatibility with previous versions. All experiments
+should eventually be deleted, once used by all versions of all datasets.
+
+#### Eg:
+
+class Experiment(enum.Enum): EXP_A = enum.auto() # Short description of
+experiment.
+
+class MyBuilder(...): VERSION = tfds.core.Version('1.2.3', experiments={
+tfds.core.Experiment.EXP_A: True, })
+
+## Class Members
+
+*   `DUMMY` <a id="DUMMY"></a>

docs/api_docs/python/tfds/core/GeneratorBasedBuilder.md

@@ -4,6 +4,7 @@
 <meta itemprop="property" content="builder_config"/>
 <meta itemprop="property" content="data_dir"/>
 <meta itemprop="property" content="info"/>
+<meta itemprop="property" content="version"/>
 <meta itemprop="property" content="__init__"/>
 <meta itemprop="property" content="as_dataset"/>
 <meta itemprop="property" content="download_and_prepare"/>
@@ -61,7 +62,9 @@ Callers must pass arguments as keyword arguments.
     subdirectories and versions.
 *   <b>`version`</b>: `str`. Optional version at which to load the dataset. An
     error is raised if specified version cannot be satisfied. Eg: '1.2.3',
-    '1.2.*'.
+    '1.2.*'. The special value "experimental_latest" will use the highest
+    version, even if not default. This is not recommended unless you know what
+    you are doing, as the version could be broken.
 
 ## Properties
 
@@ -75,6 +78,8 @@ Callers must pass arguments as keyword arguments.
 
 <a href="../../tfds/core/DatasetInfo.md"><code>tfds.core.DatasetInfo</code></a> for this builder.
 
+<h3 id="version"><code>version</code></h3>
+
 ## Methods
 
 <h3 id="as_dataset"><code>as_dataset</code></h3>

docs/api_docs/python/tfds/core/NamedSplit.md

@@ -4,6 +4,7 @@
 <meta itemprop="property" content="__add__"/>
 <meta itemprop="property" content="__eq__"/>
 <meta itemprop="property" content="__init__"/>
+<meta itemprop="property" content="__ne__"/>
 <meta itemprop="property" content="get_read_instruction"/>
 <meta itemprop="property" content="subsplit"/>
 </div>
@@ -88,6 +89,14 @@ __eq__(other)
 
 Equality: tfds.Split.TRAIN == 'train'.
 
+<h3 id="__ne__"><code>__ne__</code></h3>
+
+```python
+__ne__(other)
+```
+
+InEquality: tfds.Split.TRAIN != 'test'.
+
 <h3 id="get_read_instruction"><code>get_read_instruction</code></h3>
 
 ``` python

docs/api_docs/python/tfds/core/SplitBase.md

@@ -3,6 +3,7 @@
 <meta itemprop="path" content="Stable" />
 <meta itemprop="property" content="__add__"/>
 <meta itemprop="property" content="__eq__"/>
+<meta itemprop="property" content="__ne__"/>
 <meta itemprop="property" content="get_read_instruction"/>
 <meta itemprop="property" content="subsplit"/>
 </div>
@@ -44,11 +45,6 @@ There are three parts to the composition:
   3) The `SplitReadInstruction` is then used in the `tf.data.Dataset` pipeline
      to define which files to read and how to skip examples within file.
 
-  ```
-  files_to_read = read_instruction.split_info
-  slice_per_file = read_instruction.slice_list
-  ```
-
 ## Methods
 
 <h3 id="__add__"><code>__add__</code></h3>
@@ -67,6 +63,14 @@ __eq__(other)
 
 Equality: tfds.Split.TRAIN == 'train'.
 
+<h3 id="__ne__"><code>__ne__</code></h3>
+
+```python
+__ne__(other)
+```
+
+InEquality: tfds.Split.TRAIN != 'test'.
+
 <h3 id="get_read_instruction"><code>get_read_instruction</code></h3>
 
 ``` python