documentation fixes for vote schema and remove vote-model.md in place of vote schema doc, and link to vote schema doc from data-models index

bigchaindb/common/schema/vote.yaml

@@ -25,12 +25,12 @@ properties:
     type: "string"
     pattern: "[1-9a-zA-Z^OIl]{86,88}"
     description:
-        Ed25519 signature of the ``vote`` object.
+        Ed25519 signature of the `Vote Details`_ object.
   vote:
     type: "object"
     additionalProperties: false
     description: |
-        Vote details to be signed.
+        `Vote Details`_ to be signed.
     required:
     - invalid_reason
     - is_block_valid
@@ -41,12 +41,12 @@ properties:
       previous_block:
         "$ref": "#/definitions/sha3_hexdigest"
         description: |
-          Sha3 identifier of the block that preceeds the block being voted on.
+          SHA3 identifier of the block that preceeds the block being voted on.
           The notion of a "previous" block is subject to vote.
       voting_for_block:
         "$ref": "#/definitions/sha3_hexdigest"
         description: |
-          Sha3 identifier of the block being voted on.
+          SHA3 identifier of the block being voted on.
       is_block_valid:
         type: "boolean"
         description: |
@@ -56,6 +56,10 @@ properties:
         - type: "string"
           description: |
             Reason the block is voted invalid, or ``null``.
+
+            .. container:: notice
+
+              **Note**: The invalid_reason was not being used and may be dropped in a future version of BigchainDB. See Issue `#217 <https://github.com/bigchaindb/bigchaindb/issues/217>`_ on GitHub.
         - type: "null"
       timestamp:
         type: "string"

docs/server/generate_schema_documentation.py

@@ -35,6 +35,15 @@ TPL_STYLES = """
          font-size: 100%%;
          font-family: monospace;
     }
+    .document .section p {
+        margin-bottom: 16px;
+    }
+    .notice {
+        margin: 0px 16px 16px 16px;
+        background-color: white;
+        border: 1px solid gold;
+        padding: 3px 6px;
+    }
     </style>
 """
 

docs/server/source/data-models/index.rst

@@ -16,4 +16,4 @@ This section unpacks each one in turn.
    asset-model
    crypto-conditions
    block-model
-   vote-model
+   The Vote Model <../schema/vote>

docs/server/source/data-models/vote-model.md

@@ -1,19 +0,0 @@
-# The Vote Model
-
-A vote has the following structure:
-
-```json
-{
-    "node_pubkey": "<the public key of the voting node>",
-    "vote": {
-        "voting_for_block": "<id of the block the node is voting for>",
-        "previous_block": "<id of the block previous to this one>",
-        "is_block_valid": "<true|false>",
-        "invalid_reason": "<None|DOUBLE_SPEND|TRANSACTIONS_HASH_MISMATCH|NODES_PUBKEYS_MISMATCH",
-        "timestamp": "<Unix time when the vote was generated, provided by the voting node>"
-    },
-    "signature": "<signature of vote>"
-}
-```
-
-Note: The `invalid_reason` was not being used and may be dropped in a future version of BigchainDB. See [Issue #217](https://github.com/bigchaindb/bigchaindb/issues/217) on GitHub.

docs/server/source/schema/vote.rst

@@ -29,7 +29,7 @@ Vote.signature
 
 **type:** string
 
-Ed25519 signature of the ``vote`` object.
+Ed25519 signature of the `Vote Details`_ object.
 
 
 Vote.vote
@@ -37,7 +37,7 @@ Vote.vote
 
 **type:** object
 
-Vote details to be signed.
+`Vote Details`_ to be signed.
 
 
 
@@ -46,7 +46,7 @@ Vote details to be signed.
 Vote Details
 ------------
 
-Vote details to be signed.
+`Vote Details`_ to be signed.
 
 
 Vote.previous_block
@@ -54,7 +54,7 @@ Vote.previous_block
 
 **type:** string
 
-Sha3 identifier of the block that preceeds the block being voted on.
+SHA3 identifier of the block that preceeds the block being voted on.
 The notion of a "previous" block is subject to vote.
 
 
@@ -64,7 +64,7 @@ Vote.voting_for_block
 
 **type:** string
 
-Sha3 identifier of the block being voted on.
+SHA3 identifier of the block being voted on.
 
 
 
@@ -84,6 +84,10 @@ Vote.invalid_reason
 
 Reason the block is voted invalid, or ``null``.
 
+.. container:: notice
+
+  **Note**: The invalid_reason was not being used and may be dropped in a future version of BigchainDB. See Issue `#217 <https://github.com/bigchaindb/bigchaindb/issues/217>`_ on GitHub.
+
 
 
 Vote.timestamp
@@ -115,4 +119,13 @@ to the system time of the node.
          font-size: 100%;
          font-family: monospace;
     }
+    .document .section p {
+        margin-bottom: 16px;
+    }
+    .notice {
+        margin: 0px 16px 16px 16px;
+        background-color: white;
+        border: 1px solid gold;
+        padding: 3px 6px;
+    }
     </style>