Merge branch 'master' of git.clinicalfuture.com:arvados
[arvados.git] / 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 navorder: {navorder}
37 ---
38
39 h1. {resource}
40
41 A **{resource}** represents...
42
43 h2. Methods
44
45 See "REST methods for working with Arvados resources":/api/methods.html
46
47 API endpoint base: @https://{{{{ site.arvados_api_host }}}}/arvados/v1/{res_api_endpoint}@
48
49 h2. Creation
50
51 h3. Prerequisites
52
53 Prerequisites for creating a {resource}.
54
55 h3. Side effects
56
57 Side effects of creating a {resource}.
58
59 h2. Resources
60
61 Each {resource} has, in addition to the usual "attributes of Arvados resources":resources.html:
62
63 table(table table-bordered table-condensed).
64 |_. Attribute|_. Type|_. Description|_. Example|
65 """.format(
66     resource=resource,
67     navorder=navorder,
68     res_api_endpoint=res_api_endpoint))
69
70         for prop in properties:
71             if prop not in ['id', 'uuid', 'href', 'kind', 'etag', 'self_link',
72                             'owner_uuid', 'created_at',
73                             'modified_by_client_uuid',
74                             'modified_by_user_uuid',
75                             'modified_at']:
76                 f.write('|{name}|{type}|||\n'.format(**prop))
77