First pass at Python doc generator...(originally JJ's commit)

daspecster · Jul 22, 2016 · Feb 11, 2016 · May 4, 2016 · Jul 20, 2016 · Jul 20, 2016
commit 45f5189c238356c2355d2c1249514e42412051a0
diff --git a/docs/json/manifest.json b/docs/json/manifest.json
@@ -0,0 +1,20 @@
+{
+  "lang": "python",
+  "friendlyLang": "Python",
+  "markdown": "python",
+  "versions": [
+    "v0.9.0",
+    "v0.8.0",
+    "v0.7.1",
+    "v0.7.0",
+    "v0.6.0",
+    "v0.5.0",
+    "master"
+  ],
+  "content": "json",
+  "home": "home.html",
+  "package": {
+    "title": "PyPI",
+    "href": "https://pypi.python.org/pypi/gcloud"
+  }
+}
diff --git a/docs/json/toc.json b/docs/json/toc.json
@@ -0,0 +1,179 @@
+{
+  "guides": [{
+    "title": "Authentication",
+    "id": "authentication",
+    "edit": "https://github.com/GoogleCloudPlatform/gcloud-common/edit/master/authentication/readme.md",
+    "contents": [
+      "https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/readme.md",
+      "authentication.md"
+    ]
+  }, {
+    "title": "FAQ",
+    "id": "faq",
+    "edit": "https://github.com/GoogleCloudPlatform/gcloud-common/edit/master/faq/readme.md",
+    "contents": "https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/faq/readme.md"
+  }, {
+    "title": "Troubleshooting",
+    "id": "troubleshooting",
+    "edit": "https://github.com/GoogleCloudPlatform/gcloud-common/edit/master/troubleshooting/readme.md",
+    "contents": "https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/troubleshooting/readme.md"
+  }, {
+    "title": "Contributing",
+    "id": "contributing",
+    "edit": "https://github.com/GoogleCloudPlatform/gcloud-common/edit/master/contributing/readme.md",
+    "contents": "https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/contributing/readme.md"
+  }],
+  "services": [{
+    "title": "gcloud",
+    "id": "gcloud",
+    "contents": "index.json"
+  }, {
+    "title": "Datastore",
+    "id": "datastore",
+    "contents": "datastore/index.json",
+    "nav": [{
+      "title": "Client",
+      "id": "client",
+      "contents": "datastore/client.json",
+    }, {
+      "title": "Entities",
+      "id": "entities",
+      "contents": "datastore/entities.json",
+    }, {
+      "title": "Keys",
+      "id": "keys",
+      "contents": "datastore/keys.json",
+    }, {
+      "title": "Queries",
+      "id": "queries",
+      "contents": "datastore/queries.json",
+    }, {
+      "title": "Transactions",
+      "id": "transactions",
+      "contents": "datastore/transactions.json",
+    }, {
+      "title": "Batches",
+      "id": "batches",
+      "contents": "datastore/batches.json",
+    }]
+  }, {
+    "title": "Storage",
+    "id": "storage",
+    "contents": "storage/storage.json",
+    "nav": [{
+      "title": "Client",
+      "id": "client",
+      "contents": "storage/client.json",
+    }, {
+      "title": "Blobs / Objects",
+      "id": "objects",
+      "contents": "storage/objects.json",
+    }, {
+      "title": "Buckets",
+      "id": "buckets",
+      "contents": "storage/buckets.json",
+    }, {
+      "title": "ACL",
+      "id": "acl",
+      "contents": "storage/acl.json",
+    }]
+  }, {
+    "title": "Pub/Sub",
+    "implemented": ">=0.5.0",
+    "id": "pubsub",
+    "contents": "pubsub/index.json",
+    "nav": [{
+      "title": "Client",
+      "id": "client",
+      "contents": "pubsub/client.json",
+    }, {
+      "title": "Topics",
+      "id": "topics",
+      "contents": "pubsub/topics.json",
+    }, {
+      "title": "Subscriptions",
+      "id": "subscriptions",
+      "contents": "pubsub/subscriptions.json",
+    }, {
+      "title": "Message",
+      "id": "message",
+      "contents": "pubsub/message.json",
+    }]
+  }, {
+    "title": "BigQuery",
+    "implemented": ">=0.7.0",
+    "id": "bigquery",
+    "contents": "bigquery/index.json",
+    "nav": [{
+      "title": "Client",
+      "id": "client",
+      "contents": "bigquery/client.json",
+    }, {
+      "title": "Datasets",
+      "id": "datasets",
+      "contents": "bigquery/datasets.json",
+    }, {
+      "title": "Jobs",
+      "id": "jobs",
+      "contents": "bigquery/jobs.json",
+    }, {
+      "title": "Tables",
+      "id": "tables",
+      "contents": "bigquery/tables.json",
+    }]
+  }, {
+    "title": "Resource Manager",
+    "implemented": ">=0.8.0",
+    "id": "resource-manager",
+    "contents": "resource-manager/index.json",
+    "nav": [{
+      "title": "Client",
+      "id": "client",
+      "contents": "resource-manager/client.json",
+    }, {
+      "title": "Projects",
+      "id": "projects",
+      "contents": "resource-manager/projects.json",
+    }]
+  }, {
+    "title": "DNS",
+    "implemented": ">=0.8.0",
+    "id": "dns",
+    "contents": "dns/index.json",
+    "nav": [{
+      "title": "Client",
+      "id": "client",
+      "contents": "dns/client.json",
+    }, {
+      "title": "Managed Zones",
+      "id": "managed-zones",
+      "contents": "dns/managed-zones.json",
+    }, {
+      "title": "Resource Record Sets",
+      "id": "resource-record-sets",
+      "contents": "dns/resource-record-sets.json",
+    }, {
+      "title": "Change Sets",
+      "id": "change-sets",
+      "contents": "dns/change-sets.json",
+    }]
+  }, {
+    "title": "Cloud Search",
+    "implemented": ">=0.8.0",
+    "id": "cloud-search",
+    "contents": "cloud-search/index.json",
+    "nav": [{
+      "title": "Client",
+      "id": "client",
+      "contents": "cloud-search/client.json",
+    }, {
+      "title": "Indexes",
+      "id": "indexes",
+      "contents": "cloud-search/indexes.json",
+    }, {
+      "title": "Documents",
+      "id": "documents",
+      "contents": "cloud-search/documents.json",
+    }]
+  }],
+}
diff --git a/scripts/generate_json_docs.py b/scripts/generate_json_docs.py
@@ -0,0 +1,126 @@
+import argparse
+import json
+
+from parinx.parser import parse_docstring
+import pdoc
+
+
+class Module(object):
+    def __init__(self, module_id, name, description=None, methods=None):
+        self.module_id = module_id
+        self.name = name
+        self.description = description
+        self.methods = methods or []
+
+    @classmethod
+    def from_module_name(cls, name):
+        module = pdoc.Module(pdoc.import_module(name), allsubmodules=True)
+
+        methods = module.functions() + module.variables()
+        methods.extend(module.classes())
+        for c in module.classes():
+            methods.extend(c.doc.values())
+
+        return cls(module_id=name,
+                name=name.split('.')[-1].title(),
+                description=module.docstring,
+                methods=[Method.from_pdoc(m) for m in methods])
+
+    def to_dict(self):
+        return {'id': self.module_id, 'name': self.name,
+                'description': self.description,
+                'methods': [m.to_dict() for m in self.methods]}
+
+
+class Method(object):
+
+    def __init__(self, method_id, name, is_class, examples=None, metadata=None,
+            params=None, exceptions=None, returns=None):
+        self.method_id = method_id
+        self.name = name
+        self.examples = examples or []
+        self.params = params or []
+        self.exceptions = exceptions or []
+        self.returns = returns or []
+
+        if is_class:
+            self.type = 'constructor'
+        else:
+            self.type = 'instance'
+
+    def add_param(self, param):
+        self.params.append(param)
+
+    def add_example(self, example):
+        self.examples.append({'code': example})
+
+    def set_returns(self, param_type, description):
+        self.returns = [{'types': [param_type], 'description': description}]
+
+    def to_dict(self):
+        return {'id': self.method_id, 'name': self.name,
+                'examples': self.examples,
+                'params': [p.to_dict() for p in self.params],
+                'exceptions': self.exceptions, 'returns': self.returns}
+
+    @classmethod
+    def from_pdoc(cls, element):
+        is_class = isinstance(element, pdoc.Class)
+        method = cls(element.refname, element.name, is_class)
+
+        if element.docstring:
+            if not isinstance(element, pdoc.Class) and element.cls:
+                cls = element.cls.cls
+            else:
+                cls = None
+
+            method_info = parse_docstring(element.docstring, cls)
+
+            for name, data in method_info['arguments'].items():
+                param = Param.from_docstring_section(name, data)
+                method.add_param(param)
+
+            if method_info.get('example'):
+                method.add_example(method_info['example'])
+
+            #if 'return' in method_info:
+            if method_info.get('return'):
+                if len(method_info['return']['type_name']) > 1:
+                    method.set_returns(method_info['return']['type_name'],
+                                       method_info['return']['description'])
+
+        return method
+
+
+class Param(object):
+
+    def __init__(self, name, description=None, types=None, optional=None,
+            nullable=None):
+        self.name = name
+        self.description = description
+        self.types = types or []
+        self.optional = optional
+        self.nullable = nullable
+
+    def to_dict(self):
+        return {'name': self.name, 'description': self.description,
+                'types': self.types, 'optional': self.optional,
+                'nullable': self.nullable}
+
+    @classmethod
+    def from_docstring_section(cls, name, data):
+        return cls(name=name, description=data['description'],
+                types=[data['type_name']])
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Document Python modules.')
+    parser.add_argument('module', help='The module name (ie, requests.api)')
+    args = parser.parse_args()
+
+    module = Module.from_module_name(args.module)
+    print json.dumps(module.to_dict(), indent=2)
+
+
+if __name__ == '__main__':
+    main()