FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Add basic readme generator (#580) · enterstudio/python-docs-samples@530ab8a · GitHub

/ python-docs-samples Public
forked from GoogleCloudPlatform/python-docs-samples

Commit 530ab8a

Browse files
Jon Wayne Parrott
authored
Add basic readme generator (GoogleCloudPlatform#580)
1 parent c7ab55f commit 530ab8a

10 files changed

Lines changed: 681 additions & 12 deletions

File tree

‎nox.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -320,3 +320,12 @@ def mark_if_necessary(requirement):
320320
for requirement in sorted(requirements, key=lambda s: s.lower()):
321321
if not requirement.startswith('#'):
322322
f.write(requirement)
323+
324+
325+
def session_readmegen(session):
326+
session.install('-r', 'testing/requirements-dev.txt')
327+
328+
in_files = list(list_files('.', 'README.rst.in'))
329+
330+
for in_file in in_files:
331+
session.run('python', 'scripts/readme-gen/readme_gen.py', in_file)

‎scripts/readme-gen/readme_gen.py‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
#!/usr/bin/env python
2+
3+
# Copyright 2016 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+
"""Generates READMEs using configuration defined in yaml."""
18+
19+
import argparse
20+
import io
21+
import os
22+
import subprocess
23+
24+
import jinja2
25+
import yaml
26+
27+
28+
jinja_env = jinja2.Environment(
29+
trim_blocks=True,
30+
loader=jinja2.FileSystemLoader(
31+
os.path.abspath(os.path.join(os.path.dirname(__file__), 'templates'))))
32+
33+
README_TMPL = jinja_env.get_template('README.tmpl.rst')
34+
35+
36+
def get_help(file):
37+
return subprocess.check_output(['python', file, '--help'])
38+
39+
40+
def main():
41+
parser = argparse.ArgumentParser()
42+
parser.add_argument('source')
43+
parser.add_argument('--destination', default='README.rst')
44+
45+
args = parser.parse_args()
46+
47+
source = os.path.abspath(args.source)
48+
root = os.path.dirname(source)
49+
destination = os.path.join(root, args.destination)
50+
51+
jinja_env.globals['get_help'] = get_help
52+
53+
with io.open(source, 'r') as f:
54+
config = yaml.load(f)
55+
56+
# This allows get_help to execute in the right directory.
57+
os.chdir(root)
58+
59+
output = README_TMPL.render(config)
60+
61+
with io.open(destination, 'w') as f:
62+
f.write(output)
63+
64+
if __name__ == '__main__':
65+
main()

‎scripts/readme-gen/templates/README.tmpl.rst‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
{# The following line is a lie. BUT! Once jinja2 is done with it, it will
2+
become truth! #}
3+
.. This file is automatically generated. Do not edit this file directly.
4+
5+
{{product.name}} Python Samples
6+
===============================================================================
7+
8+
This directory contains samples for {{product.name}}. {{product.description}}
9+
10+
.. _{{product.name}}: {{product.url}}
11+
12+
{% if setup %}
13+
Setup
14+
-------------------------------------------------------------------------------
15+
16+
{% for section in setup %}
17+
18+
{% include section + '.tmpl.rst' %}
19+
20+
{% endfor %}
21+
{% endif %}
22+
23+
{% if samples %}
24+
Samples
25+
-------------------------------------------------------------------------------
26+
27+
{% for sample in samples %}
28+
{{sample.name}}
29+
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
30+
31+
{{sample.description}}
32+
33+
To run this sample:
34+
35+
.. code-block:: bash
36+
37+
$ python {{sample.file}}
38+
{% if sample.show_help %}
39+
40+
{{get_help(sample.file)|indent}}
41+
{% endif %}
42+
43+
44+
{% endfor %}
45+
{% endif %}
46+
47+
{% if cloud_client_library %}
48+
49+
The client library
50+
-------------------------------------------------------------------------------
51+
52+
This sample uses the `Google Cloud Client Library for Python <ccl-docs>`_.
53+
You can read the documentation for more details on API usage and use GitHub
54+
to `browse the source <ccl-source>`_ and `report issues <ccl-issues>`_.
55+
56+
.. ccl-docs: https://googlecloudplatform.github.io/google-cloud-python/
57+
.. ccl-source: https://github.com/GoogleCloudPlatform/google-cloud-python
58+
.. ccl-issues: https://github.com/GoogleCloudPlatform/google-cloud-python/issues
59+
60+
{% endif %}
61+
62+
.. _Google Cloud SDK: https://cloud.google.com/sdk/

‎scripts/readme-gen/templates/auth.tmpl.rst‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
Authentication
2+
++++++++++++++
3+
4+
Authentication is typically done through `Application Default Credentials`_,
5+
which means you do not have to change the code to authenticate as long as
6+
your environment has credentials. You have a few options for setting up
7+
authentication:
8+
9+
{% if not no_sdk_credentials %}
10+
#. When running locally, use the `Google Cloud SDK`_
11+
12+
.. code-block:: bash
13+
14+
gcloud beta auth application-default login
15+
16+
{% endif %}
17+
18+
#. When running on App Engine or Compute Engine, credentials are already
19+
set-up. However, you may need to configure your Compute Engine instance
20+
with `additional scopes <gce-auth>`_.
21+
22+
#. You can create a `Service Account key file`_. This file can be used to
23+
authenticate to Google Cloud Platform services from any environment. To use
24+
the file, set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to
25+
the path to the key file, for example:
26+
27+
.. code-block:: bash
28+
29+
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service_account.json
30+
31+
.. _Application Default Credentials: https://cloud.google.com/docs/authentication#getting_credentials_for_server-centric_flow
32+
.. _gce-auth: https://cloud.google.com/compute/docs/authentication#using
33+
.. _Service Account key file: https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount

‎scripts/readme-gen/templates/install_deps.tmpl.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Install Dependencies
2+
++++++++++++++++++++
3+
4+
#. Install `pip`_ and `virtualenv`_ if you do not already have them.
5+
6+
#. Create a virtualenv. Samples are compatible with Python 2.7 and 3.4+.
7+
8+
.. code-block:: bash
9+
10+
$ virtualenv env
11+
$ source env/bin/activate
12+
13+
#. Install the dependencies needed to run the samples.
14+
15+
.. code-block:: bash
16+
17+
$ pip install -r requirements.txt
18+
19+
.. _pip: https://pip.pypa.io/
20+
.. _virtualenv: https://virtualenv.pypa.io/

‎storage/api/README.md‎

Lines changed: 0 additions & 12 deletions
This file was deleted.

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL