doc/gen_api_schema_docs.py

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