diff --git a/appengine/bigquery/README.md b/appengine/bigquery/README.md index def5e7c1a617..0dc4b7cdb563 100644 --- a/appengine/bigquery/README.md +++ b/appengine/bigquery/README.md @@ -2,6 +2,15 @@ This sample demonstrates [authenticating to BigQuery in App Engine using OAuth2](https://cloud.google.com/bigquery/authentication). + +These samples are used on the following documentation pages: + +> +* https://cloud.google.com/bigquery/authentication +* https://cloud.google.com/monitoring/api/authentication + + + Refer to the [App Engine Samples README](../README.md) for information on how to run and deploy this sample. ## Setup diff --git a/appengine/blobstore/README.md b/appengine/blobstore/README.md new file mode 100644 index 000000000000..d708d72cbf1d --- /dev/null +++ b/appengine/blobstore/README.md @@ -0,0 +1,9 @@ +# App Engine Blobstore Sample + + +These samples are used on the following documentation page: + +> https://cloud.google.com/appengine/docs/python/blobstore/ + + + --> diff --git a/appengine/images/README.md b/appengine/images/README.md index 367db816a5c1..f4164204c542 100644 --- a/appengine/images/README.md +++ b/appengine/images/README.md @@ -3,4 +3,11 @@ This is a sample app for Google App Engine that demonstrates the [Images Python API](https://cloud.google.com/appengine/docs/python/images/usingimages). + +These samples are used on the following documentation page: + +> https://cloud.google.com/appengine/docs/python/images/usingimages + + + Refer to the [App Engine Samples README](../README.md) for information on how to run and deploy this sample. diff --git a/appengine/localtesting/README.md b/appengine/localtesting/README.md new file mode 100644 index 000000000000..0d45442f02b1 --- /dev/null +++ b/appengine/localtesting/README.md @@ -0,0 +1,10 @@ +# App Engine Local Testing Samples + +These samples show how to do automated testing of App Engine applications. + + +These samples are used on the following documentation page: + +> https://cloud.google.com/appengine/docs/python/tools/localunittesting + + diff --git a/appengine/memcache/guestbook/README.md b/appengine/memcache/guestbook/README.md index 051f0d4b2fc7..9adf18d0f745 100644 --- a/appengine/memcache/guestbook/README.md +++ b/appengine/memcache/guestbook/README.md @@ -1,5 +1,12 @@ # Memcache Guestbook Sample -This is a sample app for Google App Engine that demonstrates the [Memcache Python API](https://cloud.google.com/appengine/docs/python/memcache/usingmemcache). +This is a sample app for Google App Engine that demonstrates the Memcache Python API. + + +These samples are used on the following documentation page: + +> https://cloud.google.com/appengine/docs/python/memcache/usingmemcache + + Refer to the [App Engine Samples README](../../README.md) for information on how to run and deploy this sample. diff --git a/appengine/multitenancy/README.md b/appengine/multitenancy/README.md index bfc161b18db1..3097ac92961b 100644 --- a/appengine/multitenancy/README.md +++ b/appengine/multitenancy/README.md @@ -2,4 +2,11 @@ This sample demonstrates how to use Google App Engine's [Namespace Manager API](https://cloud.google.com/appengine/docs/python/multitenancy/multitenancy). + +These samples are used on the following documentation page: + +> https://cloud.google.com/appengine/docs/python/multitenancy/namespaces + + + Refer to the [App Engine Samples README](../README.md) for information on how to run and deploy this sample. diff --git a/appengine/ndb/overview/README.md b/appengine/ndb/overview/README.md index b32b8a65be19..35d6b218e694 100644 --- a/appengine/ndb/overview/README.md +++ b/appengine/ndb/overview/README.md @@ -2,4 +2,11 @@ This is a sample app for Google App Engine that demonstrates the [Datastore NDB Python API](https://cloud.google.com/appengine/docs/python/ndb/). + +These samples are used on the following documentation page: + +> https://cloud.google.com/appengine/docs/python/ndb/ + + + Refer to the [App Engine Samples README](../../README.md) for information on how to run and deploy this sample. diff --git a/appengine/ndb/transactions/README.md b/appengine/ndb/transactions/README.md index 34a1da4cde7f..78dc33ab2692 100644 --- a/appengine/ndb/transactions/README.md +++ b/appengine/ndb/transactions/README.md @@ -1,7 +1,14 @@ ## App Engine Datastore NDB Transactions Sample -This is a sample app for Google App Engine that exercises the [NDB Transactions Python API](https://cloud.google.com/appengine/docs/python/ndb/transactions) +This is a sample app for Google App Engine that demonstrates the [NDB Transactions Python API](https://cloud.google.com/appengine/docs/python/ndb/transactions) This app presents a list of notes. After you submit a note with a particular title, you may not change that note or submit a new note with the same title. There are multiple note pages available. + +These samples are used on the following documentation page: + +> https://cloud.google.com/appengine/docs/python/ndb/transactions + + + Refer to the [App Engine Samples README](../../README.md) for information on how to run and deploy this sample. diff --git a/bigquery/api/README.md b/bigquery/api/README.md new file mode 100644 index 000000000000..aa021b0919fd --- /dev/null +++ b/bigquery/api/README.md @@ -0,0 +1,16 @@ +# BigQuery API Samples + + +These samples are used on the following documentation pages: + +> +* https://cloud.google.com/bigquery/exporting-data-from-bigquery +* https://cloud.google.com/bigquery/authentication +* https://cloud.google.com/bigquery/bigquery-api-quickstart +* https://cloud.google.com/bigquery/docs/managing_jobs_datasets_projects +* https://cloud.google.com/bigquery/streaming-data-into-bigquery +* https://cloud.google.com/bigquery/docs/data +* https://cloud.google.com/bigquery/querying-data +* https://cloud.google.com/bigquery/loading-data-into-bigquery + + diff --git a/compute/api/README.md b/compute/api/README.md new file mode 100644 index 000000000000..3f95f09a9e06 --- /dev/null +++ b/compute/api/README.md @@ -0,0 +1,13 @@ +# Compute Engine API Samples + + +These samples are used on the following documentation page: + +> https://cloud.google.com/compute/docs/tutorials/python-guide + + + + + + + diff --git a/monitoring/api/README.md b/monitoring/api/README.md new file mode 100644 index 000000000000..953e3545ab94 --- /dev/null +++ b/monitoring/api/README.md @@ -0,0 +1,10 @@ +# Cloud Monitoring API Samples + + +These samples are used on the following documentation pages: + +> +* https://cloud.google.com/monitoring/demos/ +* https://cloud.google.com/monitoring/api/authentication + + diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 000000000000..5b071c5ebdd3 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1 @@ +These scripts are used for the maintenance of this repository and are not necessarily meant as samples. diff --git a/scripts/auto_link_to_docs.py b/scripts/auto_link_to_docs.py new file mode 100755 index 000000000000..3b5e437cf682 --- /dev/null +++ b/scripts/auto_link_to_docs.py @@ -0,0 +1,144 @@ +#!/usr/bin/env python + +# Copyright (C) 2013 Google Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +""" +Process docs-links.json and updates all READMEs and replaces + + + +With a generated list of documentation backlinks. +""" + +from collections import defaultdict +import json +import os +import re + + +REPO_ROOT = os.path.abspath(os.path.join( + os.path.dirname(__file__), + '..')) +DOC_SITE_ROOT = 'https://cloud.google.com' +AUTO_DOC_LINK_EXP = re.compile( + r'.*?\n', + re.DOTALL) + + +def invert_docs_link_map(docs_links): + """ + The docs links map is in this format: + + { + "doc_path": [ + "file_path", + ] + } + + This transforms it to: + + { + "file_path": [ + "doc_path", + ] + } + """ + files_to_docs = defaultdict(list) + for doc, files in docs_links.iteritems(): + for file in files: + files_to_docs[file].append(doc) + files_to_docs[file] = list(set(files_to_docs[file])) + + return files_to_docs + + +def collect_docs_for_readmes(files_to_docs): + """ + There's a one-to-many relationship between readmes and files. This method + finds the readme for each file and consolidates all docs references. + """ + readmes_to_docs = defaultdict(list) + for file, docs in files_to_docs.iteritems(): + readme = get_readme_path(file) + readmes_to_docs[readme].extend(docs) + readmes_to_docs[readme] = list(set(readmes_to_docs[readme])) + return readmes_to_docs + + +def linkify(docs): + """Adds the documentation site root to doc paths, creating a full URL.""" + return [DOC_SITE_ROOT + x for x in docs] + + +def replace_contents(file_path, regex, new_content): + with open(file_path, 'r+') as f: + content = f.read() + content = regex.sub(new_content, content) + f.seek(0) + f.write(content) + + +def get_readme_path(file_path): + """Gets the readme for an associated sample file, basically just the + README.md in the same directory.""" + dir = os.path.dirname(file_path) + readme = os.path.join( + REPO_ROOT, dir, 'README.md') + return readme + + +def generate_doc_link_statement(docs): + links = linkify(docs) + if len(links) == 1: + return """ +These samples are used on the following documentation page: + +> {} + + +""".format(links.pop()) + else: + return """ +These samples are used on the following documentation pages: + +> +{} + + +""".format('\n'.join(['* {}'.format(x) for x in links])) + + +def update_readme(readme_path, docs): + if not os.path.exists(readme_path): + print('{} doesn\'t exist'.format(readme_path)) + return + replace_contents( + readme_path, + AUTO_DOC_LINK_EXP, + generate_doc_link_statement(docs)) + print('Updated {}'.format(readme_path)) + + +def main(): + docs_links = json.load(open( + os.path.join(REPO_ROOT, 'scripts', 'docs-links.json'), 'r')) + files_to_docs = invert_docs_link_map(docs_links) + readmes_to_docs = collect_docs_for_readmes(files_to_docs) + + for readme, docs in readmes_to_docs.iteritems(): + update_readme(readme, docs) + +if __name__ == '__main__': + main() diff --git a/scripts/docs-links.json b/scripts/docs-links.json new file mode 100644 index 000000000000..be1ed7e1798f --- /dev/null +++ b/scripts/docs-links.json @@ -0,0 +1,87 @@ +{ + "/appengine/docs/python/ndb/": [ + "appengine/ndb/overview/main.py" + ], + "/storage/transfer/create-client": [ + "storage/transfer_service/create_client.py" + ], + "/storage/docs/json_api/v1/json-api-python-samples": [ + "storage/api/list_objects.py" + ], + "/bigquery/querying-data": [ + "bigquery/api/async_query.py", + "bigquery/api/sync_query.py" + ], + "/bigquery/bigquery-api-quickstart": [ + "bigquery/api/getting_started.py" + ], + "/bigquery/docs/managing_jobs_datasets_projects": [ + "bigquery/api/list_datasets_projects.py" + ], + "/appengine/docs/python/blobstore/": [ + "appengine/blobstore/main.py" + ], + "/appengine/docs/python/images/usingimages": [ + "appengine/images/main.py" + ], + "/compute/docs/tutorials/python-guide": [ + "compute/api/create_instance.py", + "compute/api/startup-script.sh" + ], + "/docs/authentication": [ + "storage/api/list_objects.py" + ], + "/bigquery/loading-data-into-bigquery": [ + "bigquery/api/load_data_from_csv.py", + "bigquery/api/load_data_by_post.py" + ], + "/bigquery/streaming-data-into-bigquery": [ + "bigquery/api/streaming.py" + ], + "/appengine/docs/python/memcache/usingmemcache": [ + "appengine/memcache/guestbook/main.py" + ], + "/monitoring/demos/": [ + "monitoring/api/auth.py" + ], + "/appengine/docs/python/multitenancy/namespaces": [ + "appengine/multitenancy/memcache.py", + "appengine/multitenancy/datastore.py", + "appengine/multitenancy/taskqueue.py" + ], + "/bigquery/docs/data": [ + "bigquery/api/sync_query.py" + ], + "/bigquery/authentication": [ + "appengine/bigquery/main.py", + "bigquery/api/getting_started.py" + ], + "/bigquery/exporting-data-from-bigquery": [ + "bigquery/api/export_data_to_cloud_storage.py" + ], + "/appengine/docs/python/ndb/transactions": [ + "appengine/ndb/transactions/main.py" + ], + "/monitoring/api/authentication": [ + "appengine/bigquery/app.yaml", + "monitoring/api/auth.py", + "appengine/bigquery/main.py" + ], + "/storage/transfer/create-transfer": [ + "storage/transfer_service/nearline_request.py", + "storage/transfer_service/aws_request.py", + "storage/transfer_service/transfer_check.py" + ], + "/storage/docs/authentication": [ + "storage/api/list_objects.py" + ], + "/appengine/docs/python/tools/localunittesting": [ + "appengine/localtesting/runner.py", + "appengine/localtesting/test_task_queue.py", + "appengine/localtesting/test_login.py", + "appengine/localtesting/queue.yaml", + "appengine/localtesting/test_mail.py", + "appengine/localtesting/test_env_vars.py", + "appengine/localtesting/test_datastore.py" + ] +} diff --git a/storage/api/README.md b/storage/api/README.md new file mode 100644 index 000000000000..287f60f010cf --- /dev/null +++ b/storage/api/README.md @@ -0,0 +1,11 @@ +# Cloud Storage API Samples + + +These samples are used on the following documentation pages: + +> +* https://cloud.google.com/storage/docs/json_api/v1/json-api-python-samples +* https://cloud.google.com/storage/docs/authentication +* https://cloud.google.com/docs/authentication + + diff --git a/storage/transfer_service/README.md b/storage/transfer_service/README.md index 14e593b4cb6c..3833f62935bc 100644 --- a/storage/transfer_service/README.md +++ b/storage/transfer_service/README.md @@ -2,6 +2,15 @@ This app creates two types of transfers using the Transfer Service tool. + +These samples are used on the following documentation pages: + +> +* https://cloud.google.com/storage/transfer/create-transfer +* https://cloud.google.com/storage/transfer/create-client + + + ## Prerequisites 1. Set up a project on Google Developers Console.