Merge pull request #1847 from bigchaindb/no-more-autogen-schema-pages-in-docs
Removed auto-generated tx & vote schema documentation
This commit is contained in:
Troy McConaghy
GitHub
commit
c2acefa6f0
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<style>
|
||||
#%(container)s h2 {
|
||||
border-top: solid 3px #6ab0de;
|
||||
background-color: #e7f2fa;
|
||||
padding: 5px;
|
||||
}
|
||||
#%(container)s h3 {
|
||||
background: #f0f0f0;
|
||||
border-left: solid 3px #ccc;
|
||||
font-weight: bold;
|
||||
padding: 6px;
|
||||
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>
|
||||
"""
|
||||
|
||||
|
||||
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()
|
||||
|
|
@ -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',
|
||||
]
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <Input>` 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 <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 <Output>` 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.
|
||||
|
|
|
|||
|
|
@ -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 <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 <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 <Outputs>`.
|
||||
|
||||
- **operation**: A string indicating what kind of transaction this is,
|
||||
and how it should be validated.
|
||||
|
|
|
|||
|
|
@ -16,7 +16,5 @@ BigchainDB Server Documentation
|
|||
events/index
|
||||
drivers-clients/index
|
||||
data-models/index
|
||||
schema/transaction
|
||||
schema/vote
|
||||
release-notes
|
||||
appendices/index
|
||||
|
|
|
|||
Loading…
Reference in New Issue