make html runs generation scripts for documentation, generates http…

… server examples
bigchaindb · Nov 30, 2016 · 49726c4 · 49726c4
1 parent a30c79f
commit 49726c4
Show file tree

Hide file tree

Showing 7 changed files with 121 additions and 473 deletions.
diff --git a/.gitignore b/.gitignore
@@ -77,3 +77,7 @@ benchmarking-tests/ssh_key.py
 # Ansible-specific files
 ntools/one-m/ansible/hosts
 ntools/one-m/ansible/ansible.cfg
+
+# Just in time documentation
+docs/server/source/schema
+docs/server/source/drivers-clients/samples
diff --git a/docs/generate/__init__.py b/docs/generate/__init__.py
diff --git a/docs/server/generate_http_server_api_documentation.py b/docs/server/generate_http_server_api_documentation.py
@@ -0,0 +1,87 @@
+""" Script to build http examples for http server api docs """
+
+import json
+import os
+import os.path
+
+from bigchaindb.common.transaction import Asset, Transaction
+
+
+TPLS = {}
+
+TPLS['post-tx-request'] = """\
+POST /transactions/ HTTP/1.1
+Host: example.com
+Content-Type: application/json
+
+%(tx)s
+"""
+
+
+TPLS['post-tx-response'] = """\
+HTTP/1.1 201 Created
+Content-Type: application/json
+
+%(tx)s
+"""
+
+
+TPLS['get-tx-status-request'] = """\
+GET /transactions/%(txid)s/status HTTP/1.1
+Host: example.com
+
+"""
+
+
+TPLS['get-tx-status-response'] = """\
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "status": "valid"
+}
+"""
+
+
+TPLS['get-tx-request'] = """\
+GET /transactions/%(txid)s HTTP/1.1
+Host: example.com
+
+"""
+
+
+TPLS['get-tx-response'] = """\
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+%(tx)s
+"""
+
+
+def main():
+    """ Main function """
+    pub = '9RaWxppkP9UyYWA7NJb5FcgkzfJNPfvPX3FCNw2T5Pwb'
+    asset = Asset(None, 'e6969f87-4fc9-4467-b62a-f0dfa1c85002')
+    tx = Transaction.create([pub], [([pub], 1)], asset=asset)
+    tx_json = json.dumps(tx.to_dict(), indent=2, sort_keys=True)
+
+    base_path = os.path.join(os.path.dirname(__file__),
+                             'source/drivers-clients/samples')
+
+    if not os.path.exists(base_path):
+        os.makedirs(base_path)
+
+    for name, tpl in TPLS.items():
+        path = os.path.join(base_path, name + '.http')
+        code = tpl % {'tx': tx_json, 'txid': tx.id}
+        with open(path, 'w') as handle:
+            handle.write(code)
+
+
+def setup(*_):
+    """ Fool sphinx into think it's an extension muahaha """
+    main()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/docs/server/generate_schema_documentation.py b/docs/server/generate_schema_documentation.py
@@ -168,12 +168,20 @@ def main():
         'file': os.path.basename(__file__),
     }
 
-    path = os.path.join(os.path.dirname(__file__),
-                        'source/schema/transaction.rst')
+    base_path = os.path.join(os.path.dirname(__file__), 'source/schema')
+    path = os.path.join(base_path, 'transaction.rst')
+
+    if not os.path.exists(base_path):
+        os.makedirs(base_path)
 
     with open(path, 'w') as handle:
         handle.write(doc)
 
 
+def setup(*_):
+    """ Fool sphinx into think it's an extension muahaha """
+    main()
+
+
 if __name__ == '__main__':
     main()
diff --git a/docs/server/source/conf.py b/docs/server/source/conf.py
@@ -35,6 +35,10 @@
 with open('../../../bigchaindb/version.py') as fp:
     exec(fp.read(), _version)
 
+import os.path
+import sys
+
+sys.path.insert(0, os.path.abspath(os.path.dirname(__file__) + '/..'))
 
 extensions = [
     'sphinx.ext.autodoc',
@@ -44,6 +48,10 @@
     'sphinx.ext.napoleon',
     'sphinxcontrib.httpdomain',
     'sphinx.ext.autosectionlabel',
+    # Below are actually build steps made to look like sphinx extensions.
+    # It was the easiest way to get it running with ReadTheDocs.
+    'generate_schema_documentation',
+    'generate_http_server_api_documentation',
 ]
 
 # autodoc settings

diff --git a/docs/server/source/drivers-clients/http-client-server-api.rst b/docs/server/source/drivers-clients/http-client-server-api.rst
@@ -64,108 +64,13 @@ POST /transactions/
 
    **Example request**:
 
-   .. sourcecode:: http
-
-      POST /transactions/ HTTP/1.1
-      Host: example.com
-      Content-Type: application/json
-
-      {
-        "transaction": {
-          "conditions": [
-            {
-              "cid": 0,
-              "condition": {
-                "uri": "cc:4:20:fSlVCKNSzSl0meiwwuUk5JpJ0KLlECTqbd25KyQefFY:96",
-                "details": {
-                  "signature": null,
-                  "type": "fulfillment",
-                  "type_id": 4,
-                  "bitmask": 32,
-                  "public_key": "9RaWxppkP9UyYWA7NJb5FcgkzfJNPfvPX3FCNw2T5Pwb"
-                }
-              },
-              "amount": 1,
-              "owners_after": [
-                "9RaWxppkP9UyYWA7NJb5FcgkzfJNPfvPX3FCNw2T5Pwb"
-              ]
-            }
-          ],
-          "operation": "CREATE",
-          "asset": {
-            "divisible": false,
-            "updatable": false,
-            "data": null,
-            "id": "b57801f8-b865-4360-9d1a-3e3009f5ce01",
-            "refillable": false
-          },
-          "metadata": null,
-          "fulfillments": [
-            {
-              "fid": 0,
-              "input": null,
-              "fulfillment": "cf:4:fSlVCKNSzSl0meiwwuUk5JpJ0KLlECTqbd25KyQefFaf8bQVH1gesZGEGZepCE8_kgo-UfBrCHPlvBsnAsfq56GWjrLTyZ9NXISwcyJ3zmygnVhCMG8xzE6c9fj1-6wK",
-              "owners_before": [
-                  "9RaWxppkP9UyYWA7NJb5FcgkzfJNPfvPX3FCNw2T5Pwb"
-              ]
-            }
-          ]
-        },
-        "id": "65f1f69b6ebf995a7b2c5ae8a6fb480ce20f0e8f1eb1d77d75f37ab00ccdeec3",
-        "version": 1
-      }
+   .. literalinclude:: samples/post-tx-request.http
+      :language: http
 
    **Example response**:
 
-   .. sourcecode:: http
-
-      HTTP/1.1 201 Created
-      Content-Type: application/json
-
-      {
-        "id": "65f1f69b6ebf995a7b2c5ae8a6fb480ce20f0e8f1eb1d77d75f37ab00ccdeec3",
-        "version": 1,
-        "transaction": {
-          "conditions": [
-            {
-              "amount": 1,
-              "condition": {
-                "uri": "cc:4:20:fSlVCKNSzSl0meiwwuUk5JpJ0KLlECTqbd25KyQefFY:96",
-                "details": {
-                  "signature": null,
-                  "type_id": 4,
-                  "type": "fulfillment",
-                  "bitmask": 32,
-                  "public_key": "9RaWxppkP9UyYWA7NJb5FcgkzfJNPfvPX3FCNw2T5Pwb"
-                }
-              },
-              "owners_after": [
-                "9RaWxppkP9UyYWA7NJb5FcgkzfJNPfvPX3FCNw2T5Pwb"
-              ],
-              "cid": 0
-            }
-          ],
-          "fulfillments": [
-            {
-              "input": null,
-              "fulfillment": "cf:4:fSlVCKNSzSl0meiwwuUk5JpJ0KLlECTqbd25KyQefFaf8bQVH1gesZGEGZepCE8_kgo-UfBrCHPlvBsnAsfq56GWjrLTyZ9NXISwcyJ3zmygnVhCMG8xzE6c9fj1-6wK",
-              "fid": 0,
-              "owners_before": [
-                "9RaWxppkP9UyYWA7NJb5FcgkzfJNPfvPX3FCNw2T5Pwb"
-              ]
-            }
-          ],
-          "operation": "CREATE",
-          "asset": {
-            "updatable": false,
-            "refillable": false,
-            "divisible": false,
-            "data": null,
-            "id": "b57801f8-b865-4360-9d1a-3e3009f5ce01"
-          },
-          "metadata": null
-        }
-      }
+   .. literalinclude:: samples/post-tx-response.http
+      :language: http
 
    :statuscode 201: A new transaction was created.
    :statuscode 400: The transaction was invalid and not created.
@@ -187,21 +92,13 @@ GET /transactions/{tx_id}/status
 
    **Example request**:
 
-   .. sourcecode:: http
-
-      GET /transactions/65f1f69b6ebf995a7b2c5ae8a6fb480ce20f0e8f1eb1d77d75f37ab00ccdeec3/status HTTP/1.1
-      Host: example.com
+   .. literalinclude:: samples/get-tx-status-request.http
+      :language: http
 
    **Example response**:
 
-   .. sourcecode:: http
-
-      HTTP/1.1 200 OK
-      Content-Type: application/json
-
-      {
-        "status": "valid"
-      }
+   .. literalinclude:: samples/get-tx-status-response.http
+      :language: http
 
    :statuscode 200: A transaction with that ID was found and the status is returned.
    :statuscode 404: A transaction with that ID was not found.
@@ -222,62 +119,13 @@ GET /transactions/{tx_id}
 
    **Example request**:
 
-   .. sourcecode:: http
-
-      GET /transactions/65f1f69b6ebf995a7b2c5ae8a6fb480ce20f0e8f1eb1d77d75f37ab00ccdeec3 HTTP/1.1
-      Host: example.com
+   .. literalinclude:: samples/get-tx-request.http
+      :language: http
 
    **Example response**:
 
-   .. sourcecode:: http
-
-      HTTP/1.1 200 OK
-      Content-Type: application/json
-
-      {
-        "transaction": {
-          "conditions": [
-            {
-              "cid": 0,
-              "condition": {
-                "uri": "cc:4:20:fSlVCKNSzSl0meiwwuUk5JpJ0KLlECTqbd25KyQefFY:96",
-                "details": {
-                  "signature": null,
-                  "type": "fulfillment",
-                  "type_id": 4,
-                  "bitmask": 32,
-                  "public_key": "9RaWxppkP9UyYWA7NJb5FcgkzfJNPfvPX3FCNw2T5Pwb"
-                }
-              },
-              "amount": 1,
-              "owners_after": [
-                "9RaWxppkP9UyYWA7NJb5FcgkzfJNPfvPX3FCNw2T5Pwb"
-              ]
-            }
-          ],
-          "operation": "CREATE",
-          "asset": {
-            "divisible": false,
-            "updatable": false,
-            "data": null,
-            "id": "b57801f8-b865-4360-9d1a-3e3009f5ce01",
-            "refillable": false
-          },
-          "metadata": null,
-          "fulfillments": [
-            {
-              "fid": 0,
-              "input": null,
-              "fulfillment": "cf:4:fSlVCKNSzSl0meiwwuUk5JpJ0KLlECTqbd25KyQefFaf8bQVH1gesZGEGZepCE8_kgo-UfBrCHPlvBsnAsfq56GWjrLTyZ9NXISwcyJ3zmygnVhCMG8xzE6c9fj1-6wK",
-              "owners_before": [
-                "9RaWxppkP9UyYWA7NJb5FcgkzfJNPfvPX3FCNw2T5Pwb"
-              ]
-            }
-          ]
-        },
-        "id": "65f1f69b6ebf995a7b2c5ae8a6fb480ce20f0e8f1eb1d77d75f37ab00ccdeec3",
-        "version": 1
-      }
+   .. literalinclude:: samples/get-tx-response.http
+      :language: http
 
    :statuscode 200: A transaction with that ID was found.
    :statuscode 404: A transaction with that ID was not found.