Bigtable: docs Snippet only includes half of documentation

[sethtroisi]

Small problem with snippets_table.py for google.cloud.bigtable.row.DirectRow.clear documentation only showing half the example code (e.g. not actually showing the running of the clear command)

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

[tseaver]

@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 doesn't actually fold together the multiple segments in the same way as the DPE sample generator does.

[sethtroisi]

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]

[sethtroisi]

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}'

[tseaver]

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.