Add basic readme generator (#580)

Author: Jon Wayne Parrott

nox.py

@@ -320,3 +320,12 @@ def mark_if_necessary(requirement):
         for requirement in sorted(requirements, key=lambda s: s.lower()):
             if not requirement.startswith('#'):
                 f.write(requirement)
+
+
+def session_readmegen(session):
+    session.install('-r', 'testing/requirements-dev.txt')
+
+    in_files = list(list_files('.', 'README.rst.in'))
+
+    for in_file in in_files:
+        session.run('python', 'scripts/readme-gen/readme_gen.py', in_file)

scripts/readme-gen/readme_gen.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+
+# Copyright 2016 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.
+
+"""Generates READMEs using configuration defined in yaml."""
+
+import argparse
+import io
+import os
+import subprocess
+
+import jinja2
+import yaml
+
+
+jinja_env = jinja2.Environment(
+    trim_blocks=True,
+    loader=jinja2.FileSystemLoader(
+        os.path.abspath(os.path.join(os.path.dirname(__file__), 'templates'))))
+
+README_TMPL = jinja_env.get_template('README.tmpl.rst')
+
+
+def get_help(file):
+    return subprocess.check_output(['python', file, '--help'])
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('source')
+    parser.add_argument('--destination', default='README.rst')
+
+    args = parser.parse_args()
+
+    source = os.path.abspath(args.source)
+    root = os.path.dirname(source)
+    destination = os.path.join(root, args.destination)
+
+    jinja_env.globals['get_help'] = get_help
+
+    with io.open(source, 'r') as f:
+        config = yaml.load(f)
+
+    # This allows get_help to execute in the right directory.
+    os.chdir(root)
+
+    output = README_TMPL.render(config)
+
+    with io.open(destination, 'w') as f:
+        f.write(output)
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,62 @@
+{# The following line is a lie. BUT! Once jinja2 is done with it, it will
+    become truth! #}
+.. This file is automatically generated. Do not edit this file directly.
+
+{{product.name}} Python Samples
+===============================================================================
+
+This directory contains samples for {{product.name}}. {{product.description}}
+
+.. _{{product.name}}: {{product.url}} 
+
+{% if setup %}
+Setup
+-------------------------------------------------------------------------------
+
+{% for section in setup %}
+
+{% include section + '.tmpl.rst' %}
+
+{% endfor %}
+{% endif %}
+
+{% if samples %}
+Samples
+-------------------------------------------------------------------------------
+
+{% for sample in samples %}
+{{sample.name}}
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+{{sample.description}}
+
+To run this sample:
+
+.. code-block:: bash
+
+    $ python {{sample.file}}
+{% if sample.show_help %}
+
+    {{get_help(sample.file)|indent}}
+{% endif %}
+
+
+{% endfor %}
+{% endif %}
+
+{% if cloud_client_library %}
+
+The client library
+-------------------------------------------------------------------------------
+
+This sample uses the `Google Cloud Client Library for Python <ccl-docs>`_.
+You can read the documentation for more details on API usage and use GitHub
+to `browse the source <ccl-source>`_ and  `report issues <ccl-issues>`_.
+
+.. ccl-docs: https://googlecloudplatform.github.io/google-cloud-python/
+.. ccl-source: https://github.com/GoogleCloudPlatform/google-cloud-python
+.. ccl-issues: https://github.com/GoogleCloudPlatform/google-cloud-python/issues
+
+{% endif %}
+
+.. _Google Cloud SDK: https://cloud.google.com/sdk/

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

@@ -0,0 +1,33 @@
+Authentication
+++++++++++++++
+
+Authentication is typically done through `Application Default Credentials`_,
+which means you do not have to change the code to authenticate as long as
+your environment has credentials. You have a few options for setting up
+authentication:
+
+{% if not no_sdk_credentials %}
+#. When running locally, use the `Google Cloud SDK`_
+
+    .. code-block:: bash
+
+        gcloud beta auth application-default login
+
+{% endif %}
+
+#. When running on App Engine or Compute Engine, credentials are already
+   set-up. However, you may need to configure your Compute Engine instance
+   with `additional scopes <gce-auth>`_.
+
+#. You can create a `Service Account key file`_. This file can be used to
+   authenticate to Google Cloud Platform services from any environment. To use
+   the file, set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to
+   the path to the key file, for example:
+
+    .. code-block:: bash
+
+        export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service_account.json
+
+.. _Application Default Credentials: https://cloud.google.com/docs/authentication#getting_credentials_for_server-centric_flow
+.. _gce-auth: https://cloud.google.com/compute/docs/authentication#using
+.. _Service Account key file: https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount

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

@@ -0,0 +1,20 @@
+Install Dependencies
+++++++++++++++++++++
+
+#. Install `pip`_ and `virtualenv`_ if you do not already have them.
+
+#. Create a virtualenv. Samples are compatible with Python 2.7 and 3.4+.
+
+    .. code-block:: bash
+
+        $ virtualenv env
+        $ source env/bin/activate
+
+#. Install the dependencies needed to run the samples.
+
+    .. code-block:: bash
+
+        $ pip install -r requirements.txt
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/