Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 475b43f

Browse filesBrowse files
author
Jonathan Wayne Parrott
committed
Merge pull request GoogleCloudPlatform#143 from GoogleCloudPlatform/autogen
Adding auto doc links for READMEs.
2 parents 3e63a0b + b9cd3b0 commit 475b43f
Copy full SHA for 475b43f

File tree

Expand file treeCollapse file tree

16 files changed

+356
-2
lines changed
Filter options
Expand file treeCollapse file tree

16 files changed

+356
-2
lines changed

‎appengine/bigquery/README.md

Copy file name to clipboardExpand all lines: appengine/bigquery/README.md
+9Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@
22

33
This sample demonstrates [authenticating to BigQuery in App Engine using OAuth2](https://cloud.google.com/bigquery/authentication).
44

5+
<!-- auto-doc-link -->
6+
These samples are used on the following documentation pages:
7+
8+
>
9+
* https://cloud.google.com/bigquery/authentication
10+
* https://cloud.google.com/monitoring/api/authentication
11+
12+
<!-- end-auto-doc-link -->
13+
514
Refer to the [App Engine Samples README](../README.md) for information on how to run and deploy this sample.
615

716
## Setup

‎appengine/blobstore/README.md

Copy file name to clipboard
+9Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# App Engine Blobstore Sample
2+
3+
<!-- auto-doc-link -->
4+
These samples are used on the following documentation page:
5+
6+
> https://cloud.google.com/appengine/docs/python/blobstore/
7+
8+
<!-- end-auto-doc-link -->
9+
-->

‎appengine/images/README.md

Copy file name to clipboardExpand all lines: appengine/images/README.md
+7Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,11 @@
33
This is a sample app for Google App Engine that demonstrates the [Images Python
44
API](https://cloud.google.com/appengine/docs/python/images/usingimages).
55

6+
<!-- auto-doc-link -->
7+
These samples are used on the following documentation page:
8+
9+
> https://cloud.google.com/appengine/docs/python/images/usingimages
10+
11+
<!-- end-auto-doc-link -->
12+
613
Refer to the [App Engine Samples README](../README.md) for information on how to run and deploy this sample.

‎appengine/localtesting/README.md

Copy file name to clipboard
+10Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# App Engine Local Testing Samples
2+
3+
These samples show how to do automated testing of App Engine applications.
4+
5+
<!-- auto-doc-link -->
6+
These samples are used on the following documentation page:
7+
8+
> https://cloud.google.com/appengine/docs/python/tools/localunittesting
9+
10+
<!-- end-auto-doc-link -->

‎appengine/memcache/guestbook/README.md

Copy file name to clipboard
+8-1Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# Memcache Guestbook Sample
22

3-
This is a sample app for Google App Engine that demonstrates the [Memcache Python API](https://cloud.google.com/appengine/docs/python/memcache/usingmemcache).
3+
This is a sample app for Google App Engine that demonstrates the Memcache Python API.
4+
5+
<!-- auto-doc-link -->
6+
These samples are used on the following documentation page:
7+
8+
> https://cloud.google.com/appengine/docs/python/memcache/usingmemcache
9+
10+
<!-- end-auto-doc-link -->
411

512
Refer to the [App Engine Samples README](../../README.md) for information on how to run and deploy this sample.

‎appengine/multitenancy/README.md

Copy file name to clipboardExpand all lines: appengine/multitenancy/README.md
+7Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,11 @@
22

33
This sample demonstrates how to use Google App Engine's [Namespace Manager API](https://cloud.google.com/appengine/docs/python/multitenancy/multitenancy).
44

5+
<!-- auto-doc-link -->
6+
These samples are used on the following documentation page:
7+
8+
> https://cloud.google.com/appengine/docs/python/multitenancy/namespaces
9+
10+
<!-- end-auto-doc-link -->
11+
512
Refer to the [App Engine Samples README](../README.md) for information on how to run and deploy this sample.

‎appengine/ndb/overview/README.md

Copy file name to clipboardExpand all lines: appengine/ndb/overview/README.md
+7Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,11 @@
22

33
This is a sample app for Google App Engine that demonstrates the [Datastore NDB Python API](https://cloud.google.com/appengine/docs/python/ndb/).
44

5+
<!-- auto-doc-link -->
6+
These samples are used on the following documentation page:
7+
8+
> https://cloud.google.com/appengine/docs/python/ndb/
9+
10+
<!-- end-auto-doc-link -->
11+
512
Refer to the [App Engine Samples README](../../README.md) for information on how to run and deploy this sample.

‎appengine/ndb/transactions/README.md

Copy file name to clipboard
+8-1Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,14 @@
11
## App Engine Datastore NDB Transactions Sample
22

3-
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)
3+
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)
44

55
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.
66

7+
<!-- auto-doc-link -->
8+
These samples are used on the following documentation page:
9+
10+
> https://cloud.google.com/appengine/docs/python/ndb/transactions
11+
12+
<!-- end-auto-doc-link -->
13+
714
Refer to the [App Engine Samples README](../../README.md) for information on how to run and deploy this sample.

‎bigquery/api/README.md

Copy file name to clipboard
+16Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# BigQuery API Samples
2+
3+
<!-- auto-doc-link -->
4+
These samples are used on the following documentation pages:
5+
6+
>
7+
* https://cloud.google.com/bigquery/exporting-data-from-bigquery
8+
* https://cloud.google.com/bigquery/authentication
9+
* https://cloud.google.com/bigquery/bigquery-api-quickstart
10+
* https://cloud.google.com/bigquery/docs/managing_jobs_datasets_projects
11+
* https://cloud.google.com/bigquery/streaming-data-into-bigquery
12+
* https://cloud.google.com/bigquery/docs/data
13+
* https://cloud.google.com/bigquery/querying-data
14+
* https://cloud.google.com/bigquery/loading-data-into-bigquery
15+
16+
<!-- end-auto-doc-link -->

‎compute/api/README.md

Copy file name to clipboard
+13Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Compute Engine API Samples
2+
3+
<!-- auto-doc-link -->
4+
These samples are used on the following documentation page:
5+
6+
> https://cloud.google.com/compute/docs/tutorials/python-guide
7+
8+
<!-- end-auto-doc-link -->
9+
10+
11+
12+
13+

‎monitoring/api/README.md

Copy file name to clipboard
+10Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Cloud Monitoring API Samples
2+
3+
<!-- auto-doc-link -->
4+
These samples are used on the following documentation pages:
5+
6+
>
7+
* https://cloud.google.com/monitoring/demos/
8+
* https://cloud.google.com/monitoring/api/authentication
9+
10+
<!-- end-auto-doc-link -->

‎scripts/README.md

Copy file name to clipboard
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
These scripts are used for the maintenance of this repository and are not necessarily meant as samples.

‎scripts/auto_link_to_docs.py

Copy file name to clipboard
+144Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
#!/usr/bin/env python
2+
3+
# Copyright (C) 2013 Google Inc.
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
"""
18+
Process docs-links.json and updates all READMEs and replaces
19+
20+
<!-- auto-doc-link --><!-- end-auto-doc-link -->
21+
22+
With a generated list of documentation backlinks.
23+
"""
24+
25+
from collections import defaultdict
26+
import json
27+
import os
28+
import re
29+
30+
31+
REPO_ROOT = os.path.abspath(os.path.join(
32+
os.path.dirname(__file__),
33+
'..'))
34+
DOC_SITE_ROOT = 'https://cloud.google.com'
35+
AUTO_DOC_LINK_EXP = re.compile(
36+
r'<!-- auto-doc-link -->.*?<!-- end-auto-doc-link -->\n',
37+
re.DOTALL)
38+
39+
40+
def invert_docs_link_map(docs_links):
41+
"""
42+
The docs links map is in this format:
43+
44+
{
45+
"doc_path": [
46+
"file_path",
47+
]
48+
}
49+
50+
This transforms it to:
51+
52+
{
53+
"file_path": [
54+
"doc_path",
55+
]
56+
}
57+
"""
58+
files_to_docs = defaultdict(list)
59+
for doc, files in docs_links.iteritems():
60+
for file in files:
61+
files_to_docs[file].append(doc)
62+
files_to_docs[file] = list(set(files_to_docs[file]))
63+
64+
return files_to_docs
65+
66+
67+
def collect_docs_for_readmes(files_to_docs):
68+
"""
69+
There's a one-to-many relationship between readmes and files. This method
70+
finds the readme for each file and consolidates all docs references.
71+
"""
72+
readmes_to_docs = defaultdict(list)
73+
for file, docs in files_to_docs.iteritems():
74+
readme = get_readme_path(file)
75+
readmes_to_docs[readme].extend(docs)
76+
readmes_to_docs[readme] = list(set(readmes_to_docs[readme]))
77+
return readmes_to_docs
78+
79+
80+
def linkify(docs):
81+
"""Adds the documentation site root to doc paths, creating a full URL."""
82+
return [DOC_SITE_ROOT + x for x in docs]
83+
84+
85+
def replace_contents(file_path, regex, new_content):
86+
with open(file_path, 'r+') as f:
87+
content = f.read()
88+
content = regex.sub(new_content, content)
89+
f.seek(0)
90+
f.write(content)
91+
92+
93+
def get_readme_path(file_path):
94+
"""Gets the readme for an associated sample file, basically just the
95+
README.md in the same directory."""
96+
dir = os.path.dirname(file_path)
97+
readme = os.path.join(
98+
REPO_ROOT, dir, 'README.md')
99+
return readme
100+
101+
102+
def generate_doc_link_statement(docs):
103+
links = linkify(docs)
104+
if len(links) == 1:
105+
return """<!-- auto-doc-link -->
106+
These samples are used on the following documentation page:
107+
108+
> {}
109+
110+
<!-- end-auto-doc-link -->
111+
""".format(links.pop())
112+
else:
113+
return """<!-- auto-doc-link -->
114+
These samples are used on the following documentation pages:
115+
116+
>
117+
{}
118+
119+
<!-- end-auto-doc-link -->
120+
""".format('\n'.join(['* {}'.format(x) for x in links]))
121+
122+
123+
def update_readme(readme_path, docs):
124+
if not os.path.exists(readme_path):
125+
print('{} doesn\'t exist'.format(readme_path))
126+
return
127+
replace_contents(
128+
readme_path,
129+
AUTO_DOC_LINK_EXP,
130+
generate_doc_link_statement(docs))
131+
print('Updated {}'.format(readme_path))
132+
133+
134+
def main():
135+
docs_links = json.load(open(
136+
os.path.join(REPO_ROOT, 'scripts', 'docs-links.json'), 'r'))
137+
files_to_docs = invert_docs_link_map(docs_links)
138+
readmes_to_docs = collect_docs_for_readmes(files_to_docs)
139+
140+
for readme, docs in readmes_to_docs.iteritems():
141+
update_readme(readme, docs)
142+
143+
if __name__ == '__main__':
144+
main()

‎scripts/docs-links.json

Copy file name to clipboard
+87Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
{
2+
"/appengine/docs/python/ndb/": [
3+
"appengine/ndb/overview/main.py"
4+
],
5+
"/storage/transfer/create-client": [
6+
"storage/transfer_service/create_client.py"
7+
],
8+
"/storage/docs/json_api/v1/json-api-python-samples": [
9+
"storage/api/list_objects.py"
10+
],
11+
"/bigquery/querying-data": [
12+
"bigquery/api/async_query.py",
13+
"bigquery/api/sync_query.py"
14+
],
15+
"/bigquery/bigquery-api-quickstart": [
16+
"bigquery/api/getting_started.py"
17+
],
18+
"/bigquery/docs/managing_jobs_datasets_projects": [
19+
"bigquery/api/list_datasets_projects.py"
20+
],
21+
"/appengine/docs/python/blobstore/": [
22+
"appengine/blobstore/main.py"
23+
],
24+
"/appengine/docs/python/images/usingimages": [
25+
"appengine/images/main.py"
26+
],
27+
"/compute/docs/tutorials/python-guide": [
28+
"compute/api/create_instance.py",
29+
"compute/api/startup-script.sh"
30+
],
31+
"/docs/authentication": [
32+
"storage/api/list_objects.py"
33+
],
34+
"/bigquery/loading-data-into-bigquery": [
35+
"bigquery/api/load_data_from_csv.py",
36+
"bigquery/api/load_data_by_post.py"
37+
],
38+
"/bigquery/streaming-data-into-bigquery": [
39+
"bigquery/api/streaming.py"
40+
],
41+
"/appengine/docs/python/memcache/usingmemcache": [
42+
"appengine/memcache/guestbook/main.py"
43+
],
44+
"/monitoring/demos/": [
45+
"monitoring/api/auth.py"
46+
],
47+
"/appengine/docs/python/multitenancy/namespaces": [
48+
"appengine/multitenancy/memcache.py",
49+
"appengine/multitenancy/datastore.py",
50+
"appengine/multitenancy/taskqueue.py"
51+
],
52+
"/bigquery/docs/data": [
53+
"bigquery/api/sync_query.py"
54+
],
55+
"/bigquery/authentication": [
56+
"appengine/bigquery/main.py",
57+
"bigquery/api/getting_started.py"
58+
],
59+
"/bigquery/exporting-data-from-bigquery": [
60+
"bigquery/api/export_data_to_cloud_storage.py"
61+
],
62+
"/appengine/docs/python/ndb/transactions": [
63+
"appengine/ndb/transactions/main.py"
64+
],
65+
"/monitoring/api/authentication": [
66+
"appengine/bigquery/app.yaml",
67+
"monitoring/api/auth.py",
68+
"appengine/bigquery/main.py"
69+
],
70+
"/storage/transfer/create-transfer": [
71+
"storage/transfer_service/nearline_request.py",
72+
"storage/transfer_service/aws_request.py",
73+
"storage/transfer_service/transfer_check.py"
74+
],
75+
"/storage/docs/authentication": [
76+
"storage/api/list_objects.py"
77+
],
78+
"/appengine/docs/python/tools/localunittesting": [
79+
"appengine/localtesting/runner.py",
80+
"appengine/localtesting/test_task_queue.py",
81+
"appengine/localtesting/test_login.py",
82+
"appengine/localtesting/queue.yaml",
83+
"appengine/localtesting/test_mail.py",
84+
"appengine/localtesting/test_env_vars.py",
85+
"appengine/localtesting/test_datastore.py"
86+
]
87+
}

‎storage/api/README.md

Copy file name to clipboard
+11Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Cloud Storage API Samples
2+
3+
<!-- auto-doc-link -->
4+
These samples are used on the following documentation pages:
5+
6+
>
7+
* https://cloud.google.com/storage/docs/json_api/v1/json-api-python-samples
8+
* https://cloud.google.com/storage/docs/authentication
9+
* https://cloud.google.com/docs/authentication
10+
11+
<!-- end-auto-doc-link -->

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.