doc/gen_api_schema_docs.py

   1 #! /usr/bin/env python
   2
   3 # gen_api_schema_docs.py
   4 #
   5 # Generate Textile documentation pages for Arvados schema resources.
   6
   7 import requests
   8 import re
   9 import os
  10
  11 r = requests.get('https://localhost:9900/arvados/v1/schema',
  12                  verify=False)
  13 if r.status_code != 200:
  14     raise Exception('Bad status code %d: %s' % (r.status_code, r.text))
  15
  16 if 'application/json' not in r.headers.get('content-type', ''):
  17     raise Exception('Unexpected content type: %s: %s' %
  18                     (r.headers.get('content-type', ''), r.text))
  19
  20 schema = r.json()
  21 navorder = 0
  22 for resource in sorted(schema.keys()):
  23     navorder = navorder + 1
  24     properties = schema[resource]
  25     res_api_endpoint = re.sub(r'([a-z])([A-Z])', r'\1_\2', resource).lower()
  26     outfile = "{}.textile".format(resource)
  27     if os.path.exists(outfile):
  28         outfile = "{}_new.textile".format(resource)
  29     print outfile, "..."
  30     with open(outfile, "w") as f:
  31         f.write("""---
  32 layout: default
  33 navsection: api
  34 navmenu: Schema
  35 title: {resource}
  36 ---
  37
  38 h1. {resource}
  39
  40 A **{resource}** represents...
  41
  42 h2. Methods
  43
  44         See "REST methods for working with Arvados resources":{{{{site.baseurl}}}}/api/methods.html
  45
  46 API endpoint base: @https://{{{{ site.arvados_api_host }}}}/arvados/v1/{res_api_endpoint}@
  47
  48 h2. Creation
  49
  50 h3. Prerequisites
  51
  52 Prerequisites for creating a {resource}.
  53
  54 h3. Side effects
  55
  56 Side effects of creating a {resource}.
  57
  58 h2. Resources
  59
  60 Each {resource} has, in addition to the usual "attributes of Arvados resources":resources.html:
  61
  62 table(table table-bordered table-condensed).
  63 |_. Attribute|_. Type|_. Description|_. Example|
  64 """.format(
  65     resource=resource,
  66     navorder=navorder,
  67     res_api_endpoint=res_api_endpoint))
  68
  69         for prop in properties:
  70             if prop not in ['id', 'uuid', 'href', 'kind', 'etag', 'self_link',
  71                             'owner_uuid', 'created_at',
  72                             'modified_by_client_uuid',
  73                             'modified_by_user_uuid',
  74                             'modified_at']:
  75                 f.write('|{name}|{type}|||\n'.format(**prop))
  76