render schema/vote.rst

bigchaindb/common/schema/vote.yaml

@@ -7,6 +7,10 @@ title: Vote Schema
 description: |
     A Vote is an endorsement of a Block (identified by a hash) by
     a node (identified by a public key).
+
+    The outer Vote object contains the details of the vote being made
+    as well as the signature and identifying information of the node
+    passing the vote.
 required:
 - node_pubkey
 - signature
@@ -34,16 +38,6 @@ properties:
     - voting_for_block
     - timestamp
     properties:
-      invalid_reason:
-        anyOf:
-        - type: "string"
-          description: |
-            Reason the block is voted invalid, or ``null``.
-        - type: "null"
-      is_block_valid:
-        type: "boolean"
-        description: |
-          This field is ``true`` if the block was deemed valid by the node.
       previous_block:
         "$ref": "#/definitions/sha3_hexdigest"
         description: |
@@ -53,6 +47,16 @@ properties:
         "$ref": "#/definitions/sha3_hexdigest"
         description: |
           Sha3 identifier of the block being voted on.
+      is_block_valid:
+        type: "boolean"
+        description: |
+          This field is ``true`` if the block was deemed valid by the node.
+      invalid_reason:
+        anyOf:
+        - type: "string"
+          description: |
+            Reason the block is voted invalid, or ``null``.
+        - type: "null"
       timestamp:
         type: "string"
         pattern: "[0-9]{10}"

docs/server/generate_schema_documentation.py

@@ -5,7 +5,7 @@ import os.path
 
 import yaml
 
-from bigchaindb.common.schema import TX_SCHEMA_PATH
+from bigchaindb.common.schema import TX_SCHEMA_PATH, VOTE_SCHEMA_PATH
 
 
 TPL_PROP = """\
@@ -84,6 +84,23 @@ Metadata
 """ + TPL_STYLES
 
 
+def generate_transaction_docs():
+    schema = load_schema(TX_SCHEMA_PATH)
+    defs = schema['definitions']
+
+    doc = TPL_TRANSACTION % {
+        'transaction': render_section('Transaction', schema),
+        'condition': render_section('Condition', defs['condition']),
+        'fulfillment': render_section('Fulfillment', defs['fulfillment']),
+        'asset': render_section('Asset', defs['asset']),
+        'metadata': render_section('Metadata', defs['metadata']['anyOf'][0]),
+        'container': 'transaction-schema',
+        'file': os.path.basename(__file__),
+    }
+
+    write_schema_doc('transaction', doc)
+
+
 TPL_VOTE = """\
 ..  This file was auto generated by %(file)s
 
@@ -91,9 +108,32 @@ TPL_VOTE = """\
 Vote Schema
 ===========
 
+Vote
+----
+
+%(vote)s
+
+Vote Details
+------------
+
+%(vote_details)s
+
 """ + TPL_STYLES
 
 
+def generate_vote_docs():
+    schema = load_schema(VOTE_SCHEMA_PATH)
+
+    doc = TPL_VOTE % {
+        'vote': render_section('Vote', schema),
+        'vote_details': render_section('Vote', schema['properties']['vote']),
+        'container': 'vote-schema',
+        'file': os.path.basename(__file__),
+    }
+
+    write_schema_doc('vote', doc)
+
+
 def ordered_load_yaml(path):
     """ Custom YAML loader to preserve key order """
     class OrderedLoader(yaml.SafeLoader):
@@ -116,23 +156,6 @@ def load_schema(path):
     return schema
 
 
-def generate_transaction_docs():
-    schema = load_schema(TX_SCHEMA_PATH)
-    defs = schema['definitions']
-
-    doc = TPL_TRANSACTION % {
-        'transaction': render_section('Transaction', schema),
-        'condition': render_section('Condition', defs['condition']),
-        'fulfillment': render_section('Fulfillment', defs['fulfillment']),
-        'asset': render_section('Asset', defs['asset']),
-        'metadata': render_section('Metadata', defs['metadata']['anyOf'][0]),
-        'container': 'transaction-schema',
-        'file': os.path.basename(__file__),
-    }
-
-    write_schema_doc('transaction', doc)
-
-
 def write_schema_doc(name, doc):
     # Check base path exists
     base_path = os.path.join(os.path.dirname(__file__), 'source/schema')
@@ -197,6 +220,7 @@ def resolve_ref(ref):
 def main():
     """ Main function """
     generate_transaction_docs()
+    generate_vote_docs()
 
 
 def setup(*_):

docs/server/source/index.rst

@@ -16,5 +16,6 @@ BigchainDB Server Documentation
    topic-guides/index
    data-models/index
    schema/transaction
+   schema/vote
    release-notes
    appendices/index

docs/server/source/schema/vote.rst

@@ -0,0 +1,118 @@
+..  This file was auto generated by generate_schema_documentation.py
+
+===========
+Vote Schema
+===========
+
+Vote
+----
+
+A Vote is an endorsement of a Block (identified by a hash) by
+a node (identified by a public key).
+
+The outer Vote object contains the details of the vote being made
+as well as the signature and identifying information of the node
+passing the vote.
+
+
+Vote.node_pubkey
+^^^^^^^^^^^^^^^^
+
+**type:** string
+
+Ed25519 public key identifying the voting node.
+
+
+
+Vote.signature
+^^^^^^^^^^^^^^
+
+**type:** string
+
+Ed25519 signature of the ``vote`` object.
+
+
+Vote.vote
+^^^^^^^^^
+
+**type:** object
+
+Vote details to be signed.
+
+
+
+
+
+Vote Details
+------------
+
+Vote details to be signed.
+
+
+Vote.previous_block
+^^^^^^^^^^^^^^^^^^^
+
+**type:** string
+
+Sha3 identifier of the block that preceeds the block being voted on.
+The notion of a "previous" block is subject to vote.
+
+
+
+Vote.voting_for_block
+^^^^^^^^^^^^^^^^^^^^^
+
+**type:** string
+
+Sha3 identifier of the block being voted on.
+
+
+
+Vote.is_block_valid
+^^^^^^^^^^^^^^^^^^^
+
+**type:** boolean
+
+This field is ``true`` if the block was deemed valid by the node.
+
+
+
+Vote.invalid_reason
+^^^^^^^^^^^^^^^^^^^
+
+**type:** string or null
+
+Reason the block is voted invalid, or ``null``.
+
+
+
+Vote.timestamp
+^^^^^^^^^^^^^^
+
+**type:** string
+
+Unix timestamp that the vote was created by the node, according
+to the system time of the node.
+
+
+
+
+
+
+.. raw:: html
+
+    <style>
+    #vote-schema h2 {
+         border-top: solid 3px #6ab0de;
+         background-color: #e7f2fa;
+         padding: 5px;
+    }
+    #vote-schema h3 {
+         background: #f0f0f0;
+         border-left: solid 3px #ccc;
+         font-weight: bold;
+         padding: 6px;
+         font-size: 100%;
+         font-family: monospace;
+    }
+    </style>