diff --git a/.gitignore b/.gitignore index 20d71296..c58d0db8 100644 --- a/.gitignore +++ b/.gitignore @@ -77,7 +77,6 @@ ntools/one-m/ansible/hosts ntools/one-m/ansible/ansible.cfg # Just in time documentation -docs/server/source/schema docs/server/source/http-samples # Terraform state files diff --git a/bigchaindb/common/schema/README.md b/bigchaindb/common/schema/README.md index 3c8451b0..4b2cf873 100644 --- a/bigchaindb/common/schema/README.md +++ b/bigchaindb/common/schema/README.md @@ -3,11 +3,12 @@ This directory contains the schemas for the different JSON documents BigchainDB uses. The aim is to provide: - - a strict definition/documentation of the data structures used in BigchainDB - - a language independent tool to validate the structure of incoming/outcoming - data (there are several ready to use - [implementations](http://json-schema.org/implementations.html) written in - different languages) + +- a strict definition of the data structures used in BigchainDB +- a language independent tool to validate the structure of incoming/outcoming + data (there are several ready to use + [implementations](http://json-schema.org/implementations.html) written in + different languages) ## Learn about JSON Schema diff --git a/docs/server/generate_schema_documentation.py b/docs/server/generate_schema_documentation.py deleted file mode 100644 index c94fe3a9..00000000 --- a/docs/server/generate_schema_documentation.py +++ /dev/null @@ -1,241 +0,0 @@ -""" Script to render transaction schema into .rst document """ - -from collections import OrderedDict -import os.path - -import yaml - -from bigchaindb.common.schema import TX_SCHEMA_PATH, VOTE_SCHEMA_PATH - - -TPL_PROP = """\ -%(title)s -%(underline)s - -**type:** %(type)s - -%(description)s -""" - - -TPL_STYLES = """ -.. raw:: html - - -""" - - -TPL_TRANSACTION = TPL_STYLES + """\ -.. This file was auto generated by %(file)s - -================== -Transaction Schema -================== - -* `Transaction`_ - -* Input_ - -* Output_ - -* Asset_ - -* Metadata_ - - -Transaction ------------ - -%(transaction)s - -Input ------ - -%(input)s - -Output ------- - -%(output)s - -Asset ------ - -%(asset)s - -Metadata --------- - -%(metadata)s -""" - - -def generate_transaction_docs(): - schema = load_schema(TX_SCHEMA_PATH) - defs = schema['definitions'] - - doc = TPL_TRANSACTION % { - 'transaction': render_section('Transaction', schema), - 'output': render_section('Output', defs['output']), - 'input': render_section('Input', defs['input']), - '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 = TPL_STYLES + """\ -.. This file was auto generated by %(file)s - -=========== -Vote Schema -=========== - -Vote ----- - -%(vote)s - -Vote Details ------------- - -%(vote_details)s - -""" - - -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): - pass - - def construct_mapping(loader, node): - loader.flatten_mapping(node) - return OrderedDict(loader.construct_pairs(node)) - OrderedLoader.add_constructor( - yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, - construct_mapping) - with open(path) as handle: - return yaml.load(handle, OrderedLoader) - - -def load_schema(path): - global DEFS - schema = ordered_load_yaml(path) - DEFS = schema['definitions'] - return schema - - -def write_schema_doc(name, doc): - # Check base path exists - base_path = os.path.join(os.path.dirname(__file__), 'source/schema') - if not os.path.exists(base_path): - os.makedirs(base_path) - # Write doc - path = os.path.join(base_path, '%s.rst' % name) - with open(path, 'w') as handle: - handle.write(doc) - - -def render_section(section_name, obj): - """ Render a domain object and it's properties """ - out = [obj['description']] - for name, prop in obj.get('properties', {}).items(): - try: - title = '%s.%s' % (section_name, name) - out += [TPL_PROP % { - 'title': title, - 'underline': '^' * len(title), - 'description': property_description(prop), - 'type': property_type(prop), - }] - except Exception as exc: - raise ValueError('Error rendering property: %s' % name, exc) - return '\n\n'.join(out + ['']) - - -def property_description(prop): - """ Get description of property """ - if 'description' in prop: - return prop['description'] - if '$ref' in prop: - return property_description(resolve_ref(prop['$ref'])) - if 'anyOf' in prop: - return property_description(prop['anyOf'][0]) - raise KeyError('description') - - -def property_type(prop): - """ Resolve a string representing the type of a property """ - if 'type' in prop: - if prop['type'] == 'array': - return 'array (%s)' % property_type(prop['items']) - return prop['type'] - if 'anyOf' in prop: - return ' or '.join(property_type(p) for p in prop['anyOf']) - if '$ref' in prop: - return property_type(resolve_ref(prop['$ref'])) - raise ValueError('Could not resolve property type') - - -DEFINITION_BASE_PATH = '#/definitions/' - - -def resolve_ref(ref): - """ Resolve definition reference """ - assert ref.startswith(DEFINITION_BASE_PATH) - return DEFS[ref[len(DEFINITION_BASE_PATH):]] - - -def main(): - """ Main function """ - generate_transaction_docs() - generate_vote_docs() - - -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 index 756a8d13..e272baf4 100644 --- a/docs/server/source/conf.py +++ b/docs/server/source/conf.py @@ -51,7 +51,6 @@ extensions = [ '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', ] diff --git a/docs/server/source/data-models/inputs-outputs.rst b/docs/server/source/data-models/inputs-outputs.rst index 4e246bfe..52214421 100644 --- a/docs/server/source/data-models/inputs-outputs.rst +++ b/docs/server/source/data-models/inputs-outputs.rst @@ -26,7 +26,6 @@ An input has the following structure: You can think of the ``fulfills`` object as a pointer to an output on another transaction: the output that this input is spending/transferring. A CREATE transaction should have exactly one input. That input can contain one or more ``owners_before``, a ``fulfillment`` (with one signature from each of the owners-before), and the value of ``fulfills`` should be ``null``). A TRANSFER transaction should have at least one input, and the value of ``fulfills`` should not be ``null``. -See the reference on :ref:`inputs ` for more description about the meaning of each field. The ``fulfillment`` string fulfills the condition in the output that is being spent (transferred). To calculate it: @@ -62,7 +61,6 @@ An output has the following structure: The :ref:`page about conditions ` explains the contents of a ``condition``. The list of ``public_keys`` is always the "owners" of the asset at the time the transaction completed, but before the next transaction started. -See the reference on :ref:`outputs ` for more description about the meaning of each field. Note that ``amount`` must be a string (e.g. ``"7"``). In a TRANSFER transaction, the sum of the output amounts must be the same as the sum of the outputs that it transfers (i.e. the sum of the input amounts). For example, if a TRANSFER transaction has two outputs, one with ``"amount": "2"`` and one with ``"amount": "3"``, then the sum of the outputs is 5 and so the sum of the outputs-being-transferred must also be 5. diff --git a/docs/server/source/data-models/transaction-model.rst b/docs/server/source/data-models/transaction-model.rst index b4f2a4f1..4c2e2a0f 100644 --- a/docs/server/source/data-models/transaction-model.rst +++ b/docs/server/source/data-models/transaction-model.rst @@ -19,20 +19,18 @@ Here's some explanation of the contents: - **id**: The ID of the transaction and also the hash of the transaction (loosely speaking). See below for an explanation of how it's computed. It's also the database primary key. -- **version**: The version-number of :ref:`the transaction schema `. As of BigchainDB Server 1.0.0, the only allowed value is ``"1.0"``. +- **version**: The version-number of the transaction schema. As of BigchainDB Server 1.0.0, the only allowed value is ``"1.0"``. - **inputs**: List of inputs. Each input spends/transfers a previous output by satisfying/fulfilling the crypto-conditions on that output. A CREATE transaction should have exactly one input. A TRANSFER transaction should have at least one input (i.e. ≥1). - For more details, see the subsection about :ref:`inputs `. - **outputs**: List of outputs. Each output indicates the crypto-conditions which must be satisfied by anyone wishing to spend/transfer that output. It also indicates the number of shares of the asset tied to that output. - For more details, see the subsection about :ref:`outputs `. - **operation**: A string indicating what kind of transaction this is, and how it should be validated. diff --git a/docs/server/source/index.rst b/docs/server/source/index.rst index ec6efef0..42c7e4be 100644 --- a/docs/server/source/index.rst +++ b/docs/server/source/index.rst @@ -16,7 +16,5 @@ BigchainDB Server Documentation events/index drivers-clients/index data-models/index - schema/transaction - schema/vote release-notes appendices/index