Repository: googleapis/google-cloud-python

Issue:
Bigtable: docs Snippet only includes half of documentation
Small problem with `snippets_table.py` for `google.cloud.bigtable.row.DirectRow.clear` [documentation](https://googleapis.github.io/google-cloud-python/latest/bigtable/row.html#google.cloud.bigtable.row.DirectRow.clear) only showing half the example code (e.g. not actually showing the running of the clear command)

![Screenshot from 2019-03-16 10-42-40](https://user-images.githubusercontent.com/10172976/54479283-77cde100-47d8-11e9-85e1-9441878653a4.png)

This is because the test has two parts and the snippit is only including the first. 

```
def test_bigtable_row_clear():
    # [START bigtable_row_clear]
    from google.cloud.bigtable import Client

    client = Client(admin=True)
    instance = client.instance(INSTANCE_ID)
    table = instance.table(TABLE_ID)

    row_key = b"row_key_1"
    row_obj = table.row(row_key)
    row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, b"cell-val")
    # [END bigtable_row_clear]

    mutation_size = row_obj.get_mutations_size()
    assert mutation_size > 0

    # [START bigtable_row_clear]
    row_obj.clear()
    # [END bigtable_row_clear]

    mutation_size = row_obj.get_mutations_size()
    assert mutation_size == 0
```



Discussion:
@sethtroisi Thanks for the report!

@crwilcox, @theacodes This bug actually affetcs anywhere in Sphinx where we try to address snippets which re-use the same ID:  the [`.. literalinclude::` directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html?highlight=literalinclude#directive-literalinclude) doesn't actually fold together the multiple segments in the same way as the DPE sample generator does.
It doesn't seem to be a very wide spread problem

```
$ grep -rih '^\s*# \[start' | sed 's/^\s*//' | sort | uniq -c | sort -n
      1 # [START acl_print]
      1 # [START acl_revoke_write]
...
      1 # [START upload_from_file]
      2 # [START bigquery_undelete_table]
      2 # [START bigtable_admins_policy]
      2 # [START bigtable_column_family_name]
      2 # [START bigtable_create_column_family]
      2 # [START bigtable_create_table]
      2 # [START bigtable_delete_cluster]
      2 # [START bigtable_delete_column_family]
      2 # [START bigtable_delete_instance]
      2 # [START bigtable_delete_table]
      2 # [START bigtable_list_app_profiles]
      2 # [START bigtable_list_tables]
      2 # [START bigtable_readers_policy]
      2 # [START bigtable_row_commit]
      2 # [START bigtable_row_delete]
      2 # [START bigtable_row_delete_cell]
      2 # [START bigtable_row_delete_cells]
      2 # [START bigtable_row_row_key]
      2 # [START bigtable_row_set_cell]
      2 # [START bigtable_sample_row_keys]
      2 # [START bigtable_set_iam_policy]
      2 # [START bigtable_update_column_family]
      2 # [START bigtable_users_policy]
      2 # [START bigtable_viewers_policy]
      2 # [START spanner_test_dml_read_your_writes]
      2 # [START spanner_test_dml_update]
      2 # [START spanner_test_dml_with_mutation]
      3 # [START bigquery_load_table_gcs_avro_truncate]
      3 # [START bigquery_load_table_gcs_csv_autodetect]
      3 # [START bigquery_load_table_gcs_csv_truncate]
      3 # [START bigquery_load_table_gcs_json_autodetect]
      3 # [START bigquery_load_table_gcs_json_truncate]
      3 # [START bigquery_load_table_gcs_orc_truncate]
      3 # [START bigquery_load_table_gcs_parquet_truncate]
      4 # [START bigtable_row_clear]
```
Looking for unmatched tags with 

`grep -hri '^\s*# \[\(END\|START\)' | sed -e 's/\s*# \[//' -e 's/]$//' | awk '{print $2, $1}' | sort | uniq -c | paste -d" " - - | awk '{print $1, $4, $6, $3, $2, $5}'`
My inclination is to remove the assertions nested between the same-named blocks (perhaps moving them to the bottom, with assignments where needed).  The snippets are certainly not functioning as unit tests, and their primary purpose is documentation, rather than system testing.

Resolving patch:
diff --git a/bigtable/docs/snippets.py b/bigtable/docs/snippets.py
--- a/bigtable/docs/snippets.py
+++ b/bigtable/docs/snippets.py
@@ -204,20 +204,18 @@ def test_bigtable_list_clusters_in_project():
 
 
 def test_bigtable_list_app_profiles():
-    # [START bigtable_list_app_profiles]
-    from google.cloud.bigtable import Client
-
-    client = Client(admin=True)
-    instance = client.instance(INSTANCE_ID)
-    # [END bigtable_list_app_profiles]
-
-    app_profile = instance.app_profile(
+    app_profile = Config.INSTANCE.app_profile(
         app_profile_id="app-prof-" + unique_resource_id("-"),
         routing_policy_type=enums.RoutingPolicyType.ANY,
     )
     app_profile = app_profile.create(ignore_warnings=True)
 
     # [START bigtable_list_app_profiles]
+    from google.cloud.bigtable import Client
+
+    client = Client(admin=True)
+    instance = client.instance(INSTANCE_ID)
+
     app_profiles_list = instance.list_app_profiles()
     # [END bigtable_list_app_profiles]
     assert len(app_profiles_list) > 0
@@ -348,22 +346,15 @@ def test_bigtable_delete_cluster():
 
 
 def test_bigtable_delete_instance():
-    # [START bigtable_delete_instance]
     from google.cloud.bigtable import Client
 
     client = Client(admin=True)
-    instance_id_to_delete = "inst-my-" + unique_resource_id("-")
-    # [END bigtable_delete_instance]
 
-    cluster_id = "clus-my-" + unique_resource_id("-")
-
-    instance = client.instance(
-        instance_id_to_delete, instance_type=PRODUCTION, labels=LABELS
-    )
+    instance = client.instance("inst-my-123", instance_type=PRODUCTION, labels=LABELS)
     cluster = instance.cluster(
-        cluster_id,
+        "clus-my-123",
         location_id=ALT_LOCATION_ID,
-        serve_nodes=SERVER_NODES,
+        serve_nodes=1,
         default_storage_type=STORAGE_TYPE,
     )
     operation = instance.create(clusters=[cluster])
@@ -371,7 +362,12 @@ def test_bigtable_delete_instance():
     operation.result(timeout=100)
 
     # [START bigtable_delete_instance]
-    instance_to_delete = client.instance(instance_id_to_delete)
+    from google.cloud.bigtable import Client
+
+    client = Client(admin=True)
+
+    instance_id = "inst-my-123"
+    instance_to_delete = client.instance(instance_id)
     instance_to_delete.delete()
     # [END bigtable_delete_instance]
 
@@ -393,16 +389,13 @@ def test_bigtable_test_iam_permissions():
 
 
 def test_bigtable_set_iam_policy_then_get_iam_policy():
+    service_account_email = Config.CLIENT._credentials.service_account_email
+
     # [START bigtable_set_iam_policy]
     from google.cloud.bigtable import Client
     from google.cloud.bigtable.policy import Policy
     from google.cloud.bigtable.policy import BIGTABLE_ADMIN_ROLE
 
-    # [END bigtable_set_iam_policy]
-
-    service_account_email = Config.CLIENT._credentials.service_account_email
-
-    # [START bigtable_set_iam_policy]
     client = Client(admin=True)
     instance = client.instance(INSTANCE_ID)
     instance.reload()
@@ -471,16 +464,13 @@ def test_bigtable_instance_admin_client():
 
 
 def test_bigtable_admins_policy():
+    service_account_email = Config.CLIENT._credentials.service_account_email
+
     # [START bigtable_admins_policy]
     from google.cloud.bigtable import Client
     from google.cloud.bigtable.policy import Policy
     from google.cloud.bigtable.policy import BIGTABLE_ADMIN_ROLE
 
-    # [END bigtable_admins_policy]
-
-    service_account_email = Config.CLIENT._credentials.service_account_email
-
-    # [START bigtable_admins_policy]
     client = Client(admin=True)
     instance = client.instance(INSTANCE_ID)
     instance.reload()
@@ -495,16 +485,13 @@ def test_bigtable_admins_policy():
 
 
 def test_bigtable_readers_policy():
+    service_account_email = Config.CLIENT._credentials.service_account_email
+
     # [START bigtable_readers_policy]
     from google.cloud.bigtable import Client
     from google.cloud.bigtable.policy import Policy
     from google.cloud.bigtable.policy import BIGTABLE_READER_ROLE
 
-    # [END bigtable_readers_policy]
-
-    service_account_email = Config.CLIENT._credentials.service_account_email
-
-    # [START bigtable_readers_policy]
     client = Client(admin=True)
     instance = client.instance(INSTANCE_ID)
     instance.reload()
@@ -519,16 +506,13 @@ def test_bigtable_readers_policy():
 
 
 def test_bigtable_users_policy():
+    service_account_email = Config.CLIENT._credentials.service_account_email
+
     # [START bigtable_users_policy]
     from google.cloud.bigtable import Client
     from google.cloud.bigtable.policy import Policy
     from google.cloud.bigtable.policy import BIGTABLE_USER_ROLE
 
-    # [END bigtable_users_policy]
-
-    service_account_email = Config.CLIENT._credentials.service_account_email
-
-    # [START bigtable_users_policy]
     client = Client(admin=True)
     instance = client.instance(INSTANCE_ID)
     instance.reload()
@@ -543,16 +527,13 @@ def test_bigtable_users_policy():
 
 
 def test_bigtable_viewers_policy():
+    service_account_email = Config.CLIENT._credentials.service_account_email
+
     # [START bigtable_viewers_policy]
     from google.cloud.bigtable import Client
     from google.cloud.bigtable.policy import Policy
     from google.cloud.bigtable.policy import BIGTABLE_VIEWER_ROLE
 
-    # [END bigtable_viewers_policy]
-
-    service_account_email = Config.CLIENT._credentials.service_account_email
-
-    # [START bigtable_viewers_policy]
     client = Client(admin=True)
     instance = client.instance(INSTANCE_ID)
     instance.reload()
diff --git a/bigtable/docs/snippets_table.py b/bigtable/docs/snippets_table.py
--- a/bigtable/docs/snippets_table.py
+++ b/bigtable/docs/snippets_table.py
@@ -131,6 +131,11 @@ def test_bigtable_create_table():
 
 
 def test_bigtable_sample_row_keys():
+    table_sample = Config.INSTANCE.table("table_id1_samplerow")
+    initial_split_keys = [b"split_key_1", b"split_key_10", b"split_key_20"]
+    table_sample.create(initial_split_keys=initial_split_keys)
+    assert table_sample.exists()
+
     # [START bigtable_sample_row_keys]
     from google.cloud.bigtable import Client
 
@@ -138,10 +143,6 @@ def test_bigtable_sample_row_keys():
     instance = client.instance(INSTANCE_ID)
 
     table = instance.table("table_id1_samplerow")
-    # [END bigtable_sample_row_keys]
-    initial_split_keys = [b"split_key_1", b"split_key_10", b"split_key_20"]
-    table.create(initial_split_keys=initial_split_keys)
-    # [START bigtable_sample_row_keys]
     data = table.sample_row_keys()
     actual_keys, offset = zip(*[(rk.row_key, rk.offset_bytes) for rk in data])
     # [END bigtable_sample_row_keys]
@@ -178,7 +179,7 @@ def test_bigtable_write_read_drop_truncate():
     response = table.mutate_rows(rows)
     # validate that all rows written successfully
     for i, status in enumerate(response):
-        if status.code is not 0:
+        if status.code != 0:
             print("Row number {} failed to write".format(i))
     # [END bigtable_mutate_rows]
     assert len(response) == len(rows)
@@ -304,7 +305,7 @@ def test_bigtable_list_tables():
     instance = client.instance(INSTANCE_ID)
     tables_list = instance.list_tables()
     # [END bigtable_list_tables]
-    assert len(tables_list) is not 0
+    assert len(tables_list) != 0
 
 
 def test_bigtable_table_name():
@@ -368,18 +369,17 @@ def test_bigtable_table_exists():
 
 
 def test_bigtable_delete_table():
+    table_del = Config.INSTANCE.table("table_id_del")
+    table_del.create()
+    assert table_del.exists()
+
     # [START bigtable_delete_table]
     from google.cloud.bigtable import Client
 
     client = Client(admin=True)
     instance = client.instance(INSTANCE_ID)
     table = instance.table("table_id_del")
-    # [END bigtable_delete_table]
-
-    table.create()
-    assert table.exists()
 
-    # [START bigtable_delete_table]
     table.delete()
     # [END bigtable_delete_table]
     assert not table.exists()
@@ -906,6 +906,15 @@ def test_bigtable_row_setcell_rowkey():
 
 
 def test_bigtable_row_delete():
+    table_row_del = Config.INSTANCE.table(TABLE_ID)
+    row_obj = table_row_del.row(b"row_key_1")
+    row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, b"cell-val")
+    row_obj.commit()
+    actual_rows_keys = []
+    for row in table_row_del.read_rows():
+        actual_rows_keys.append(row.row_key)
+    assert actual_rows_keys == [b"row_key_1"]
+
     # [START bigtable_row_delete]
     from google.cloud.bigtable import Client
 
@@ -915,16 +924,7 @@ def test_bigtable_row_delete():
 
     row_key = b"row_key_1"
     row_obj = table.row(row_key)
-    # [END bigtable_row_delete]
 
-    row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, b"cell-val")
-    row_obj.commit()
-    actual_rows_keys = []
-    for row in table.read_rows():
-        actual_rows_keys.append(row.row_key)
-    assert actual_rows_keys == [row_key]
-
-    # [START bigtable_row_delete]
     row_obj.delete()
     row_obj.commit()
     # [END bigtable_row_delete]
@@ -936,53 +936,39 @@ def test_bigtable_row_delete():
 
 
 def test_bigtable_row_delete_cell():
-    # [START bigtable_row_delete_cell]
-    from google.cloud.bigtable import Client
-
-    client = Client(admin=True)
-    instance = client.instance(INSTANCE_ID)
-    table = instance.table(TABLE_ID)
-
+    table_row_del_cell = Config.INSTANCE.table(TABLE_ID)
     row_key1 = b"row_key_1"
-    row_obj = table.row(row_key1)
-    # [END bigtable_row_delete_cell]
-
+    row_obj = table_row_del_cell.row(row_key1)
     row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, CELL_VAL1)
     row_obj.commit()
 
-    row_key2 = b"row_key_2"
-    row_obj = table.row(row_key2)
-    row_obj.set_cell(COLUMN_FAMILY_ID2, COL_NAME2, CELL_VAL2)
-    row_obj.commit()
-
     actual_rows_keys = []
-    for row in table.read_rows():
+    for row in table_row_del_cell.read_rows():
         actual_rows_keys.append(row.row_key)
-    assert actual_rows_keys == [row_key1, row_key2]
+    assert actual_rows_keys == [row_key1]
 
     # [START bigtable_row_delete_cell]
-    row_obj.delete_cell(COLUMN_FAMILY_ID2, COL_NAME2)
+    from google.cloud.bigtable import Client
+
+    client = Client(admin=True)
+    instance = client.instance(INSTANCE_ID)
+    table = instance.table(TABLE_ID)
+
+    row_key = b"row_key_1"
+    row_obj = table.row(row_key)
+
+    row_obj.delete_cell(COLUMN_FAMILY_ID, COL_NAME1)
     row_obj.commit()
     # [END bigtable_row_delete_cell]
 
-    actual_rows_keys = []
     for row in table.read_rows():
-        actual_rows_keys.append(row.row_key)
-    assert actual_rows_keys == [row_key1]
-    table.truncate(timeout=300)
+        assert not row.row_key
 
 
 def test_bigtable_row_delete_cells():
-    # [START bigtable_row_delete_cells]
-    from google.cloud.bigtable import Client
-
-    client = Client(admin=True)
-    instance = client.instance(INSTANCE_ID)
-    table = instance.table(TABLE_ID)
-
+    table_row_del_cells = Config.INSTANCE.table(TABLE_ID)
     row_key1 = b"row_key_1"
-    row_obj = table.row(row_key1)
-    # [END bigtable_row_delete_cells]
+    row_obj = table_row_del_cells.row(row_key1)
 
     row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, CELL_VAL1)
     row_obj.commit()
@@ -990,22 +976,36 @@ def test_bigtable_row_delete_cells():
     row_obj.commit()
 
     actual_rows_keys = []
-    for row in table.read_rows():
+    for row in table_row_del_cells.read_rows():
         actual_rows_keys.append(row.row_key)
     assert actual_rows_keys == [row_key1]
 
     # [START bigtable_row_delete_cells]
+    from google.cloud.bigtable import Client
+
+    client = Client(admin=True)
+    instance = client.instance(INSTANCE_ID)
+    table = instance.table(TABLE_ID)
+
+    row_key = b"row_key_1"
+    row_obj = table.row(row_key)
+
     row_obj.delete_cells(COLUMN_FAMILY_ID, [COL_NAME1, COL_NAME2])
     row_obj.commit()
     # [END bigtable_row_delete_cells]
 
-    actual_rows_keys = []
     for row in table.read_rows():
-        actual_rows_keys.append(row.row_key)
-    assert actual_rows_keys == []
+        assert not row.row_key
 
 
 def test_bigtable_row_clear():
+    table_row_clear = Config.INSTANCE.table(TABLE_ID)
+    row_obj = table_row_clear.row(b"row_key_1")
+    row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, b"cell-val")
+
+    mutation_size = row_obj.get_mutations_size()
+    assert mutation_size > 0
+
     # [START bigtable_row_clear]
     from google.cloud.bigtable import Client
 
@@ -1016,12 +1016,7 @@ def test_bigtable_row_clear():
     row_key = b"row_key_1"
     row_obj = table.row(row_key)
     row_obj.set_cell(COLUMN_FAMILY_ID, COL_NAME1, b"cell-val")
-    # [END bigtable_row_clear]
 
-    mutation_size = row_obj.get_mutations_size()
-    assert mutation_size > 0
-
-    # [START bigtable_row_clear]
     row_obj.clear()
     # [END bigtable_row_clear]
 


Test patch: