From 37e8adfc8d8249a814503a389cf834816da8154f Mon Sep 17 00:00:00 2001 From: Guan Gui Date: Wed, 14 Oct 2020 20:31:24 +1100 Subject: [PATCH] Improve and fix gRPC and Node SDK docs [skip ci] --- Makefile | 5 +- docs/contribution/update_documentation.md | 17 +++- docs/grpc/anchor_service.md | 60 ++++++------ docs/grpc/api_service.md | 76 +++++++-------- node_sdk/package-lock.json | 111 +++++++++++----------- node_sdk/package.json | 2 +- pkg/protos/markdown.tmpl | 23 ++++- 7 files changed, 160 insertions(+), 134 deletions(-) diff --git a/Makefile b/Makefile index 2f0b3e8..97733b5 100644 --- a/Makefile +++ b/Makefile @@ -18,7 +18,7 @@ # @Author: guiguan # @Date: 2019-06-03T13:42:50+10:00 # @Last modified by: guiguan -# @Last modified time: 2020-09-10T23:59:57+10:00 +# @Last modified time: 2020-10-14T20:18:17+11:00 PROJECT_NAME := proofable PROJECT_IMPORT_PATH := github.com/SouthbankSoftware/$(PROJECT_NAME) @@ -69,6 +69,7 @@ doc-build: rm -rf docs_output/book mdbook build doc-deploy: + cd docs_output/gh-pages && git config pull.ff only && git pull rsync -r --exclude=node_sdk/reference --exclude=.git --delete docs_output/book/html/ docs_output/gh-pages doc-clean: rm -rf docs/node_sdk/reference @@ -82,5 +83,5 @@ doc-go: doc-node: cd node_sdk && npm run doc doc-anchortypes: - cd docs_output/prd-releases && git config pull.ff only + cd docs_output/prd-releases && git config pull.ff only && git pull go run ./tools/anchor-types-updater diff --git a/docs/contribution/update_documentation.md b/docs/contribution/update_documentation.md index 4431dc7..5b047d3 100644 --- a/docs/contribution/update_documentation.md +++ b/docs/contribution/update_documentation.md @@ -1,5 +1,7 @@ # Update documentation +The follow operations should be performed in `master` branch unless otherwise specified + ## Setup docs compiling environment 1. Make sure the following dependencies are installed: @@ -48,7 +50,7 @@ Notes: ## Deploy updated docs -1. Make a production build of the docs +1. Make a production build of the docs: ```zsh make doc-build @@ -56,10 +58,19 @@ Notes: this will generate the htmls in `docs_output/book` -2. Sync changes to the checked out `gh-pages` branch at `docs_output/gh-pages` from `docs_output/book/html` +2. Sync changes to the directory `docs_output/gh-pages` (the checkout of `gh-pages` branch) from `docs_output/book/html`: ```zsh make doc-deploy ``` -3. Go to the `gh-pages` checkout: `cd docs_output/gh-pages`, review the changes and commit +3. Go to the `docs_output/gh-pages` directory, review changes and perform a git commit on `gh-pages` branch: + + ```zsh + cd docs_output/gh-pages + # review changes + git status + # commit + git add . + git commit -am "Some meaningful commit message" + ``` diff --git a/docs/grpc/anchor_service.md b/docs/grpc/anchor_service.md index d9e9c1c..2a1a280 100644 --- a/docs/grpc/anchor_service.md +++ b/docs/grpc/anchor_service.md @@ -30,13 +30,13 @@ Protobuf definition: [anchor/anchor.proto](https://github.com/SouthbankSoftware/ | Method Name | Request Type | Response Type | Description | | ----------- | ------------ | ------------- | ------------| -| GetAnchors | [.google.protobuf.Empty](#google.protobuf.Empty) | [Anchor](#anchor.Anchor) stream | GetAnchors gets all anchors | -| GetAnchor | [AnchorRequest](#anchor.AnchorRequest) | [Anchor](#anchor.Anchor) | GetAnchor gets an anchor | -| GetProof | [ProofRequest](#anchor.ProofRequest) | [Proof](#anchor.Proof) | GetProof gets a proof | -| SubmitProof | [SubmitProofRequest](#anchor.SubmitProofRequest) | [Proof](#anchor.Proof) | SubmitProof submits a proof for the given hash | -| VerifyProof | [VerifyProofRequest](#anchor.VerifyProofRequest) | [VerifyProofReply](#anchor.VerifyProofReply) | VerifyProof verifies the given proof. When the proof is unverifiable, an exception is thrown | -| GetBatch | [BatchRequest](#anchor.BatchRequest) | [Batch](#anchor.Batch) | GetBatch gets a batch | -| SubscribeBatches | [SubscribeBatchesRequest](#anchor.SubscribeBatchesRequest) | [Batch](#anchor.Batch) stream | SubscribeBatches subscribes to batch status updates | +| GetAnchors | [google.protobuf.Empty](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Empty) | [Anchor](#anchor) stream | GetAnchors gets all anchors | +| GetAnchor | [AnchorRequest](#anchorrequest) | [Anchor](#anchor) | GetAnchor gets an anchor | +| GetProof | [ProofRequest](#proofrequest) | [Proof](#proof) | GetProof gets a proof | +| SubmitProof | [SubmitProofRequest](#submitproofrequest) | [Proof](#proof) | SubmitProof submits a proof for the given hash | +| VerifyProof | [VerifyProofRequest](#verifyproofrequest) | [VerifyProofReply](#verifyproofreply) | VerifyProof verifies the given proof. When the proof is unverifiable, an exception is thrown | +| GetBatch | [BatchRequest](#batchrequest) | [Batch](#batch) | GetBatch gets a batch | +| SubscribeBatches | [SubscribeBatchesRequest](#subscribebatchesrequest) | [Batch](#batch) stream | SubscribeBatches subscribes to batch status updates | @@ -48,10 +48,10 @@ anchored to that blockchain | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| type | [Anchor.Type](#anchor.Anchor.Type) | | Type is the anchor type | -| status | [Anchor.Status](#anchor.Anchor.Status) | | Status is the anchor status | +| type | [Anchor.Type](#anchortype) | | Type is the anchor type | +| status | [Anchor.Status](#anchorstatus) | | Status is the anchor status | | error | [string](#string) | | Error is the error message when the anchor status is ERROR | -| supported_formats | [Proof.Format](#anchor.Proof.Format) | repeated | SupportedFormats are the supported proof formats of the anchor | +| supported_formats | [Proof.Format](#proofformat) | repeated | SupportedFormats are the supported proof formats of the anchor | @@ -64,7 +64,7 @@ type | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| type | [Anchor.Type](#anchor.Anchor.Type) | | Type is the anchor type | +| type | [Anchor.Type](#anchortype) | | Type is the anchor type | @@ -81,16 +81,16 @@ embedded in a transaction made to the blockchain | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | id | [string](#string) | | Id is the batch ID | -| anchor_type | [Anchor.Type](#anchor.Anchor.Type) | | AnchorType is the batch's anchor type | -| proof_format | [Proof.Format](#anchor.Proof.Format) | | ProofFormat is the batch's proof format, which determines how the merkle tree is constructed for the batch. | -| status | [Batch.Status](#anchor.Batch.Status) | | Status is the batch status. FLOW: created_at -> BATCHING -> flushed_at -> QUEUING -> started_at -> PROCESSING -> submitted_at -> PENDING -> finalized_at -> CONFIRMED / ERROR; * -> ERROR; if a batch has not yet reached PENDING and its anchor has restarted, the batch will be put back to QUEUING | +| anchor_type | [Anchor.Type](#anchortype) | | AnchorType is the batch's anchor type | +| proof_format | [Proof.Format](#proofformat) | | ProofFormat is the batch's proof format, which determines how the merkle tree is constructed for the batch. | +| status | [Batch.Status](#batchstatus) | | Status is the batch status. FLOW: created_at -> BATCHING -> flushed_at -> QUEUING -> started_at -> PROCESSING -> submitted_at -> PENDING -> finalized_at -> CONFIRMED / ERROR; * -> ERROR; if a batch has not yet reached PENDING and its anchor has restarted, the batch will be put back to QUEUING | | error | [string](#string) | | Error is the error message when status is ERROR | | size | [int64](#int64) | | Size is the number of hashes contained in the batch | -| created_at | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | CreateAt is the batch's created at timestamp. FLOW: created_at -> BATCHING | -| flushed_at | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | FlushedAt is the batch's flushed at timestamp. FLOW: BATCHING -> flushed_at -> QUEUING | -| started_at | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | StartedAt is the batch's started at timestamp. FLOW: QUEUING -> started_at -> PROCESSING | -| submitted_at | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | SubmittedAt is the batch's submitted at timestamp. FLOW: PROCESSING -> submitted_at -> PENDING | -| finalized_at | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | FinalizedAt is the batch's finalized at timestamp. FLOW: * -> finalized_at -> CONFIRMED / ERROR. NOTE: this is not the real block confirmed time, use the timestamp in the batch data instead | +| created_at | [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) | | CreateAt is the batch's created at timestamp. FLOW: created_at -> BATCHING | +| flushed_at | [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) | | FlushedAt is the batch's flushed at timestamp. FLOW: BATCHING -> flushed_at -> QUEUING | +| started_at | [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) | | StartedAt is the batch's started at timestamp. FLOW: QUEUING -> started_at -> PROCESSING | +| submitted_at | [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) | | SubmittedAt is the batch's submitted at timestamp. FLOW: PROCESSING -> submitted_at -> PENDING | +| finalized_at | [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) | | FinalizedAt is the batch's finalized at timestamp. FLOW: * -> finalized_at -> CONFIRMED / ERROR. NOTE: this is not the real block confirmed time, use the timestamp in the batch data instead | | hash | [string](#string) | | Hash is the batch's root hash | | data | [string](#string) | | Data is the batch data in JSON | @@ -105,7 +105,7 @@ BatchRequest represents a batch request | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | batch_id | [string](#string) | | BatchId is the batch ID | -| anchor_type | [Anchor.Type](#anchor.Anchor.Type) | | AnchorType is the batch's anchor type | +| anchor_type | [Anchor.Type](#anchortype) | | AnchorType is the batch's anchor type | @@ -120,11 +120,11 @@ the hash to the root hash of the proof's batch | ----- | ---- | ----- | ----------- | | hash | [string](#string) | | Hash is the hash the proof is proving for | | batch_id | [string](#string) | | BatchId is the proof's batch ID | -| anchor_type | [Anchor.Type](#anchor.Anchor.Type) | | AnchorType is the proof's anchor type | -| batch_status | [Batch.Status](#anchor.Batch.Status) | | BatchStatus is the proof's batch status | -| format | [Proof.Format](#anchor.Proof.Format) | | Format is the proof format | +| anchor_type | [Anchor.Type](#anchortype) | | AnchorType is the proof's anchor type | +| batch_status | [Batch.Status](#batchstatus) | | BatchStatus is the proof's batch status | +| format | [Proof.Format](#proofformat) | | Format is the proof format | | data | [string](#string) | | Data is the proof data in base64 | -| batch | [Batch](#anchor.Batch) | | Batch is the proof's batch detail | +| batch | [Batch](#batch) | | Batch is the proof's batch detail | @@ -138,7 +138,7 @@ ProofRequest represents a proof request | ----- | ---- | ----- | ----------- | | hash | [string](#string) | | Hash is the hash the proof is proving for | | batch_id | [string](#string) | | BatchId is the proof's batch ID | -| anchor_type | [Anchor.Type](#anchor.Anchor.Type) | | AnchorType is the proof's anchor type | +| anchor_type | [Anchor.Type](#anchortype) | | AnchorType is the proof's anchor type | | with_batch | [bool](#bool) | | WithBatch indicates whether to include the proof's batch detail | @@ -152,8 +152,8 @@ SubmitProofRequest represents a submit proof request | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | hash | [string](#string) | | Hash is the hash to be submitted | -| anchor_type | [Anchor.Type](#anchor.Anchor.Type) | | AnchorType is the anchor type to be used | -| format | [Proof.Format](#anchor.Proof.Format) | | Format is the proof format to be used | +| anchor_type | [Anchor.Type](#anchortype) | | AnchorType is the anchor type to be used | +| format | [Proof.Format](#proofformat) | | Format is the proof format to be used | | skip_batching | [bool](#bool) | | SkipBatching indicates whether to skip batching and submit a proof for the hash directly | | with_batch | [bool](#bool) | | WithBatch indicates whether to include the batch detail in the reply | @@ -168,7 +168,7 @@ information | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| filter | [BatchRequest](#anchor.BatchRequest) | | Filter is the batch filter. When nil, all batches of all anchors will be subscribed; otherwise, only the batches of the given anchor will be subscribed; if batch_id is non-empty, only the matched batch will be subscribed | +| filter | [BatchRequest](#batchrequest) | | Filter is the batch filter. When nil, all batches of all anchors will be subscribed; otherwise, only the batches of the given anchor will be subscribed; if batch_id is non-empty, only the matched batch will be subscribed | @@ -194,8 +194,8 @@ VerifyProofRequest represents a verify proof request | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| anchor_type | [Anchor.Type](#anchor.Anchor.Type) | | AnchorType is the proof's anchor type | -| format | [Proof.Format](#anchor.Proof.Format) | | Format is the proof format. If skipping the signature checking is desired, please use the corresponding non-signed format, eg. use CHP_PATH instead of CHP_PATH_SIGNED in request | +| anchor_type | [Anchor.Type](#anchortype) | | AnchorType is the proof's anchor type | +| format | [Proof.Format](#proofformat) | | Format is the proof format. If skipping the signature checking is desired, please use the corresponding non-signed format, eg. use CHP_PATH instead of CHP_PATH_SIGNED in request | | data | [string](#string) | | Data is the proof data in base64 | diff --git a/docs/grpc/api_service.md b/docs/grpc/api_service.md index 01e69cf..4c2c9f2 100644 --- a/docs/grpc/api_service.md +++ b/docs/grpc/api_service.md @@ -41,25 +41,25 @@ Protobuf definition: [api/api.proto](https://github.com/SouthbankSoftware/proofa | Method Name | Request Type | Response Type | Description | | ----------- | ------------ | ------------- | ------------| -| GetTries | [.google.protobuf.Empty](#google.protobuf.Empty) | [Trie](#api.Trie) stream | GetTries gets all tries. Admin privilege is required | -| GetTrie | [TrieRequest](#api.TrieRequest) | [Trie](#api.Trie) | GetTrie gets a trie | -| ImportTrie | [DataChunk](#api.DataChunk) stream | [Trie](#api.Trie) | ImportTrie creates a new trie from existing trie data. If the trie ID is not provided in the metadata, a new one will be generated | -| ExportTrie | [TrieRequest](#api.TrieRequest) | [DataChunk](#api.DataChunk) stream | ExportTrie exports a trie's data | -| CreateTrie | [.google.protobuf.Empty](#google.protobuf.Empty) | [Trie](#api.Trie) | CreateTrie creates an empty trie | -| DeleteTrie | [TrieRequest](#api.TrieRequest) | [Trie](#api.Trie) | DeleteTrie deletes a trie. This destroys everything of a trie | -| GetTrieKeyValues | [TrieKeyValuesRequest](#api.TrieKeyValuesRequest) | [KeyValue](#api.KeyValue) stream | GetTrieKeyValues gets key-values of a trie. The returned KeyValues are ordered by the keys lexicographically | -| GetTrieKeyValue | [TrieKeyValueRequest](#api.TrieKeyValueRequest) | [KeyValue](#api.KeyValue) | GetTrieKeyValue gets a key-value of a trie | -| SetTrieKeyValues | [KeyValue](#api.KeyValue) stream | [Trie](#api.Trie) | SetTrieKeyValues sets key-values of a trie. Set an empty value for a key to remove that key. Modifications to a trie will change its root hash | -| GetTrieRoots | [TrieRootsRequest](#api.TrieRootsRequest) | [TrieRoot](#api.TrieRoot) stream | GetTrieRoots gets roots of a trie. This is a series of roots showing the modification history of a trie | -| SetTrieRoot | [SetTrieRootRequest](#api.SetTrieRootRequest) | [Trie](#api.Trie) | SetTrieRoot sets the root of a trie to the given one. This will add an entry in the root history | -| GetTrieProofs | [TrieProofsRequest](#api.TrieProofsRequest) | [TrieProof](#api.TrieProof) stream | GetTrieProofs gets proofs of a trie | -| GetTrieProof | [TrieProofRequest](#api.TrieProofRequest) | [TrieProof](#api.TrieProof) | GetTrieProof gets a proof of a trie. When not_before is not provided (either nil or zero), the latest proof will be returned | -| SubscribeTrieProof | [TrieProofRequest](#api.TrieProofRequest) | [TrieProof](#api.TrieProof) stream | SubscribeTrieProof subscribes to proof changes of a trie. When not_before is not provided (either nil or zero), the latest proof will be returned | -| CreateTrieProof | [CreateTrieProofRequest](#api.CreateTrieProofRequest) | [TrieProof](#api.TrieProof) | CreateTrieProof creates a proof for a trie root | -| DeleteTrieProof | [DeleteTrieProofRequest](#api.DeleteTrieProofRequest) | [TrieProof](#api.TrieProof) | DeleteTrieProof deletes a proof for a trie root | -| VerifyTrieProof | [VerifyTrieProofRequest](#api.VerifyTrieProofRequest) | [VerifyProofReplyChunk](#api.VerifyProofReplyChunk) stream | VerifyTrieProof verifies a proof for a trie root | -| CreateKeyValuesProof | [CreateKeyValuesProofRequest](#api.CreateKeyValuesProofRequest) | [DataChunk](#api.DataChunk) stream | CreateKeyValuesProof creates a proof for the provided key-values out of a trie proof. The new proof is self-contained and can be verified independently | -| VerifyKeyValuesProof | [DataChunk](#api.DataChunk) stream | [VerifyProofReplyChunk](#api.VerifyProofReplyChunk) stream | VerifyKeyValuesProof verifies a key-values proof | +| GetTries | [google.protobuf.Empty](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Empty) | [Trie](#trie) stream | GetTries gets all tries. Admin privilege is required | +| GetTrie | [TrieRequest](#trierequest) | [Trie](#trie) | GetTrie gets a trie | +| ImportTrie | [DataChunk](#datachunk) stream | [Trie](#trie) | ImportTrie creates a new trie from existing trie data. If the trie ID is not provided in the metadata, a new one will be generated | +| ExportTrie | [TrieRequest](#trierequest) | [DataChunk](#datachunk) stream | ExportTrie exports a trie's data | +| CreateTrie | [google.protobuf.Empty](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Empty) | [Trie](#trie) | CreateTrie creates an empty trie | +| DeleteTrie | [TrieRequest](#trierequest) | [Trie](#trie) | DeleteTrie deletes a trie. This destroys everything of a trie | +| GetTrieKeyValues | [TrieKeyValuesRequest](#triekeyvaluesrequest) | [KeyValue](#keyvalue) stream | GetTrieKeyValues gets key-values of a trie. The returned KeyValues are ordered by the keys lexicographically | +| GetTrieKeyValue | [TrieKeyValueRequest](#triekeyvaluerequest) | [KeyValue](#keyvalue) | GetTrieKeyValue gets a key-value of a trie | +| SetTrieKeyValues | [KeyValue](#keyvalue) stream | [Trie](#trie) | SetTrieKeyValues sets key-values of a trie. Set an empty value for a key to remove that key. Modifications to a trie will change its root hash | +| GetTrieRoots | [TrieRootsRequest](#trierootsrequest) | [TrieRoot](#trieroot) stream | GetTrieRoots gets roots of a trie. This is a series of roots showing the modification history of a trie | +| SetTrieRoot | [SetTrieRootRequest](#settrierootrequest) | [Trie](#trie) | SetTrieRoot sets the root of a trie to the given one. This will add an entry in the root history | +| GetTrieProofs | [TrieProofsRequest](#trieproofsrequest) | [TrieProof](#trieproof) stream | GetTrieProofs gets proofs of a trie | +| GetTrieProof | [TrieProofRequest](#trieproofrequest) | [TrieProof](#trieproof) | GetTrieProof gets a proof of a trie. When not_before is not provided (either nil or zero), the latest proof will be returned | +| SubscribeTrieProof | [TrieProofRequest](#trieproofrequest) | [TrieProof](#trieproof) stream | SubscribeTrieProof subscribes to proof changes of a trie. When not_before is not provided (either nil or zero), the latest proof will be returned | +| CreateTrieProof | [CreateTrieProofRequest](#createtrieproofrequest) | [TrieProof](#trieproof) | CreateTrieProof creates a proof for a trie root | +| DeleteTrieProof | [DeleteTrieProofRequest](#deletetrieproofrequest) | [TrieProof](#trieproof) | DeleteTrieProof deletes a proof for a trie root | +| VerifyTrieProof | [VerifyTrieProofRequest](#verifytrieproofrequest) | [VerifyProofReplyChunk](#verifyproofreplychunk) stream | VerifyTrieProof verifies a proof for a trie root | +| CreateKeyValuesProof | [CreateKeyValuesProofRequest](#createkeyvaluesproofrequest) | [DataChunk](#datachunk) stream | CreateKeyValuesProof creates a proof for the provided key-values out of a trie proof. The new proof is self-contained and can be verified independently | +| VerifyKeyValuesProof | [DataChunk](#datachunk) stream | [VerifyProofReplyChunk](#verifyproofreplychunk) stream | VerifyKeyValuesProof verifies a key-values proof | @@ -72,8 +72,8 @@ CreateKeyValuesProofRequest represents a create key-values proof request | ----- | ---- | ----- | ----------- | | trie_id | [string](#string) | | TrieId is the trie ID | | proof_id | [string](#string) | | ProofId is the trie proof id | -| request | [CreateTrieProofRequest](#api.CreateTrieProofRequest) | | Request is the request to create a new trie proof that is going to prove the key-values | -| filter | [KeyValuesFilter](#api.KeyValuesFilter) | | Filter is the key-values filter (optional). When zero, all key-values will be included in the proof | +| request | [CreateTrieProofRequest](#createtrieproofrequest) | | Request is the request to create a new trie proof that is going to prove the key-values | +| filter | [KeyValuesFilter](#keyvaluesfilter) | | Filter is the key-values filter (optional). When zero, all key-values will be included in the proof | @@ -87,7 +87,7 @@ CreateTrieProofRequest represents a create trie proof request | ----- | ---- | ----- | ----------- | | trie_id | [string](#string) | | TrieId is the trie ID | | root | [string](#string) | | Root is the root hash (optional). When zero, the current root hash of the trie will be used to create the TrieProof, and the request will be blocked until all ongoing updates are finished | -| anchor_type | [anchor.Anchor.Type](#anchor.Anchor.Type) | | AnchorType is the anchor type the trie proof should be submitted to. Default to ETH | +| anchor_type | [anchor.Anchor.Type](anchor_service.html#anchortype) | | AnchorType is the anchor type the trie proof should be submitted to. Default to ETH | @@ -100,8 +100,8 @@ DataChunk represents a chunk of data transmitted in a gRPC stream | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | data | [bytes](#bytes) | | Data is the data within the DataChunk | -| trie_request | [TrieRequest](#api.TrieRequest) | | TrieRequest is the trie request | -| verify_key_values_proof_request | [VerifyKeyValuesProofRequest](#api.VerifyKeyValuesProofRequest) | | VerifyKeyValuesProofRequest is the request to verify a key-values proof | +| trie_request | [TrieRequest](#trierequest) | | TrieRequest is the trie request | +| verify_key_values_proof_request | [VerifyKeyValuesProofRequest](#verifykeyvaluesproofrequest) | | VerifyKeyValuesProofRequest is the request to verify a key-values proof | @@ -142,7 +142,7 @@ KeyValue represents a key-value | key | [bytes](#bytes) | | Key is the key of the key-value | | key_sep | [uint32](#uint32) | repeated | KeySep is the key separators for chained tries | | value | [bytes](#bytes) | | Value is the value of the key-value | -| trie_key_values_request | [TrieKeyValuesRequest](#api.TrieKeyValuesRequest) | | TrieKeyValuesRequest is the request to set or get key-values | +| trie_key_values_request | [TrieKeyValuesRequest](#triekeyvaluesrequest) | | TrieKeyValuesRequest is the request to set or get key-values | @@ -154,7 +154,7 @@ KeyValuesFilter represents a key-value filter | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| keys | [Key](#api.Key) | repeated | Keys are the keys of key-values that should be included in a key-value proof. Only those trie nodes are on the merkle paths of the given keys will be included in the proof | +| keys | [Key](#key) | repeated | Keys are the keys of key-values that should be included in a key-value proof. Only those trie nodes are on the merkle paths of the given keys will be included in the proof | @@ -167,7 +167,7 @@ RootFilter represents a root filter to query a proof | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | root | [string](#string) | | Root is the root hash. When zero, the current root hash of the trie will be used to retrieve the TrieProof, and the request will be blocked until all ongoing updates are finished | -| not_before | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | NotBefore is the not before timestamp. When nil, this constraint is not used; when zero, the latest TrieProof for the root hash will be returned | +| not_before | [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) | | NotBefore is the not before timestamp. When nil, this constraint is not used; when zero, the latest TrieProof for the root hash will be returned | @@ -209,7 +209,7 @@ TrieKeyValueRequest represents a trie key-value request | ----- | ---- | ----- | ----------- | | trie_id | [string](#string) | | TrieId is the trie ID | | root | [string](#string) | | Root is the root hash (optional). When zero, the current root hash of the trie will be used to retrieve the TrieKeyValues, and the request will be blocked until all ongoing updates are finished | -| key | [Key](#api.Key) | | Key is the key of the key-value | +| key | [Key](#key) | | Key is the key of the key-value | @@ -239,10 +239,10 @@ viewed as a snapshot of all the key-values contained in the trie | id | [string](#string) | | Id is the ID of the trie proof | | trie_id | [string](#string) | | TrieId is the trie ID | | root | [string](#string) | | Root is the root hash of the trie proven by this proof | -| created_at | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | CreatedAt is the created at timestamp. The timestamp when the proof is created | -| status | [anchor.Batch.Status](#anchor.Batch.Status) | | Status is the anchor batch status of the trie proof | +| created_at | [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) | | CreatedAt is the created at timestamp. The timestamp when the proof is created | +| status | [anchor.Batch.Status](anchor_service.html#batchstatus) | | Status is the anchor batch status of the trie proof | | error | [string](#string) | | Error is the error message when status is ERROR | -| anchor_type | [anchor.Anchor.Type](#anchor.Anchor.Type) | | AnchorType is the anchor type the trie proof has been submitted to | +| anchor_type | [anchor.Anchor.Type](anchor_service.html#anchortype) | | AnchorType is the anchor type the trie proof has been submitted to | | txn_id | [string](#string) | | TxnId is the blockchain transaction ID | | txn_uri | [string](#string) | | TxnUri is the explorer URI for the blockchain transaction | | block_time | [uint64](#uint64) | | BlockTime is the blockchain's block consensus timestamp in seconds | @@ -262,7 +262,7 @@ TrieProofRequest represents a trie proof request | ----- | ---- | ----- | ----------- | | trie_id | [string](#string) | | TrieId is the trie ID | | proof_id | [string](#string) | | ProofId is the trie proof ID | -| root_filter | [RootFilter](#api.RootFilter) | | RootFilter is the root filter. A nil filter equals a zero filter | +| root_filter | [RootFilter](#rootfilter) | | RootFilter is the root filter. A nil filter equals a zero filter | @@ -277,7 +277,7 @@ chronologically | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | trie_id | [string](#string) | | TrieId is the trie ID | -| root_filter | [RootFilter](#api.RootFilter) | | RootFilter is the root filter (optional). When nil, all TrieProofs will be returned | +| root_filter | [RootFilter](#rootfilter) | | RootFilter is the root filter (optional). When nil, all TrieProofs will be returned | @@ -303,7 +303,7 @@ lead to a new trie root | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | root | [string](#string) | | Root is the root hash of the trie | -| created_at | [google.protobuf.Timestamp](#google.protobuf.Timestamp) | | CreatedAt is the created at timestamp. The timestamp when the root is created | +| created_at | [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) | | CreatedAt is the created at timestamp. The timestamp when the root is created | @@ -317,7 +317,7 @@ in chronological order | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | trie_id | [string](#string) | | TrieId is the trie ID | -| root_filter | [RootFilter](#api.RootFilter) | | RootFilter is the root filter (optional). When nil, all TrieRoots will be returned | +| root_filter | [RootFilter](#rootfilter) | | RootFilter is the root filter (optional). When nil, all TrieRoots will be returned | @@ -356,9 +356,9 @@ stream | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | -| key_value | [KeyValue](#api.KeyValue) | | KeyValue is one of the key-values contained in the trie when the OutputKeyValues is true | -| dot_graph_chunk | [DataChunk](#api.DataChunk) | | DotGraphChunk is a chunk of the Graphviz dot graph for the trie when the OutputDotGraph is true | -| reply | [VerifyProofReply](#api.VerifyProofReply) | | VerifyProofReply is the verify proof reply, which should be the data in the last VerifyProofReplyChunk | +| key_value | [KeyValue](#keyvalue) | | KeyValue is one of the key-values contained in the trie when the OutputKeyValues is true | +| dot_graph_chunk | [DataChunk](#datachunk) | | DotGraphChunk is a chunk of the Graphviz dot graph for the trie when the OutputDotGraph is true | +| reply | [VerifyProofReply](#verifyproofreply) | | VerifyProofReply is the verify proof reply, which should be the data in the last VerifyProofReplyChunk | diff --git a/node_sdk/package-lock.json b/node_sdk/package-lock.json index 2282af2..13f2b34 100644 --- a/node_sdk/package-lock.json +++ b/node_sdk/package-lock.json @@ -2172,12 +2172,6 @@ "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz", "integrity": "sha1-x57Zf380y48robyXkLzDZkdLS3k=" }, - "at-least-node": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz", - "integrity": "sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg==", - "dev": true - }, "atob": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/atob/-/atob-2.1.2.tgz", @@ -2338,6 +2332,15 @@ "babel-preset-current-node-syntax": "^0.1.3" } }, + "backbone": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/backbone/-/backbone-1.4.0.tgz", + "integrity": "sha512-RLmDrRXkVdouTg38jcgHhyQ/2zjg7a8E6sz2zxfz21Hh17xDJYUHBZimVIt5fUyS8vbfpeSmTL3gUjTEvUV3qQ==", + "dev": true, + "requires": { + "underscore": ">=1.8.3" + } + }, "balanced-match": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz", @@ -4409,33 +4412,14 @@ "integrity": "sha1-PYyt2Q2XZWn6g1qx+OSyOhBWBac=" }, "fs-extra": { - "version": "9.0.1", - "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-9.0.1.tgz", - "integrity": "sha512-h2iAoN838FqAFJY2/qVpzFXy+EBxfVE220PalAqQLDVsFOHLJrZvut5puAbCdNv6WJk+B8ihI+k0c7JK5erwqQ==", + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", "dev": true, "requires": { - "at-least-node": "^1.0.0", "graceful-fs": "^4.2.0", - "jsonfile": "^6.0.1", - "universalify": "^1.0.0" - }, - "dependencies": { - "jsonfile": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.0.1.tgz", - "integrity": "sha512-jR2b5v7d2vIOust+w3wtFKZIfpC2pnRmFAhAC/BuweZFQR8qZzxH1OyrQ10HmdVYiXWkYUqPVsz91cG7EL2FBg==", - "dev": true, - "requires": { - "graceful-fs": "^4.1.6", - "universalify": "^1.0.0" - } - }, - "universalify": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/universalify/-/universalify-1.0.0.tgz", - "integrity": "sha512-rb6X1W158d7pRQBg5gkR8uPaSfiids68LTJQYOtEUhoJUWBdaQHsuT/EUduxXYxcrt4r5PJ4fuHW1MHT6p0qug==", - "dev": true - } + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" } }, "fs-minipass": { @@ -4883,9 +4867,9 @@ "dev": true }, "highlight.js": { - "version": "10.2.0", - "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-10.2.0.tgz", - "integrity": "sha512-OryzPiqqNCfO/wtFo619W+nPYALM6u7iCQkum4bqRmmlcTikOkmlL06i009QelynBPAlNByTQU6cBB2cOBQtCw==", + "version": "9.18.3", + "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-9.18.3.tgz", + "integrity": "sha512-zBZAmhSupHIl5sITeMqIJnYCDfAEc3Gdkqj65wC1lpI468MMQeeQkhcIAvk+RylAkxrCcI9xy9piHiXeQ1BdzQ==", "dev": true }, "hmac-drbg": { @@ -7833,6 +7817,12 @@ } } }, + "jquery": { + "version": "3.5.1", + "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.5.1.tgz", + "integrity": "sha512-XwIBPqcMn57FxfT+Go5pzySnm4KWkT1Tv7gjrpT1srtf8Weynl6R273VJ5GjkRb51IzMp5nbaPjJXMWeju2MKg==", + "dev": true + }, "js-tokens": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz", @@ -8152,9 +8142,9 @@ } }, "marked": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/marked/-/marked-1.1.1.tgz", - "integrity": "sha512-mJzT8D2yPxoPh7h0UXkB+dBj4FykPJ2OIfxAWeIHrvoHDkFxukV/29QxoFQoPM6RLEwhIFdJpmKBlqVM3s2ZIw==", + "version": "0.8.2", + "resolved": "https://registry.npmjs.org/marked/-/marked-0.8.2.tgz", + "integrity": "sha512-EGwzEeCcLniFX51DhTpmTom+dSA/MG/OBUDjnWtHbEnjAH180VzUeAw+oE4+Zv+CoYBWyRlYOTR0N8SO9R1PVw==", "dev": true }, "media-typer": { @@ -10455,29 +10445,34 @@ } }, "typedoc": { - "version": "0.19.2", - "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.19.2.tgz", - "integrity": "sha512-oDEg1BLEzi1qvgdQXc658EYgJ5qJLVSeZ0hQ57Eq4JXy6Vj2VX4RVo18qYxRWz75ifAaYuYNBUCnbhjd37TfOg==", + "version": "0.17.0-3", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.17.0-3.tgz", + "integrity": "sha512-DO2djkR4NHgzAWfNbJb2eQKsFMs+gOuYBXlQ8dOSCjkAK5DRI7ZywDufBGPUw7Ue9Qwi2Cw1DxLd3reDq8wFuQ==", "dev": true, "requires": { - "fs-extra": "^9.0.1", - "handlebars": "^4.7.6", - "highlight.js": "^10.2.0", - "lodash": "^4.17.20", - "lunr": "^2.3.9", - "marked": "^1.1.1", + "@types/minimatch": "3.0.3", + "fs-extra": "^8.1.0", + "handlebars": "^4.7.2", + "highlight.js": "^9.18.0", + "lodash": "^4.17.15", + "marked": "^0.8.0", "minimatch": "^3.0.0", "progress": "^2.0.3", - "semver": "^7.3.2", - "shelljs": "^0.8.4", - "typedoc-default-themes": "^0.11.4" + "shelljs": "^0.8.3", + "typedoc-default-themes": "0.8.0-0" } }, "typedoc-default-themes": { - "version": "0.11.4", - "resolved": "https://registry.npmjs.org/typedoc-default-themes/-/typedoc-default-themes-0.11.4.tgz", - "integrity": "sha512-Y4Lf+qIb9NTydrexlazAM46SSLrmrQRqWiD52593g53SsmUFioAsMWt8m834J6qsp+7wHRjxCXSZeiiW5cMUdw==", - "dev": true + "version": "0.8.0-0", + "resolved": "https://registry.npmjs.org/typedoc-default-themes/-/typedoc-default-themes-0.8.0-0.tgz", + "integrity": "sha512-blFWppm5aKnaPOa1tpGO9MLu+njxq7P3rtkXK4QxJBNszA+Jg7x0b+Qx0liXU1acErur6r/iZdrwxp5DUFdSXw==", + "dev": true, + "requires": { + "backbone": "^1.4.0", + "jquery": "^3.4.1", + "lunr": "^2.3.8", + "underscore": "^1.9.1" + } }, "typescript": { "version": "4.0.3", @@ -10486,9 +10481,9 @@ "dev": true }, "uglify-js": { - "version": "3.10.4", - "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.10.4.tgz", - "integrity": "sha512-kBFT3U4Dcj4/pJ52vfjCSfyLyvG9VYYuGYPmrPvAxRw/i7xHiT4VvCev+uiEMcEEiu6UNB6KgWmGtSUYIWScbw==", + "version": "3.11.2", + "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.11.2.tgz", + "integrity": "sha512-G440NU6fewtnQftSgqRV1r2A5ChKbU1gqFCJ7I8S7MPpY/eZZfLGefaY6gUZYiWebMaO+txgiQ1ZyLDuNWJulg==", "dev": true, "optional": true }, @@ -10497,6 +10492,12 @@ "resolved": "https://registry.npmjs.org/ultron/-/ultron-1.1.1.tgz", "integrity": "sha512-UIEXBNeYmKptWH6z8ZnqTeS8fV74zG0/eRU9VGkpzz+LIJNs8W/zM/L+7ctCkRrgbNnnR0xxw4bKOr0cW0N0Og==" }, + "underscore": { + "version": "1.11.0", + "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.11.0.tgz", + "integrity": "sha512-xY96SsN3NA461qIRKZ/+qox37YXPtSBswMGfiNptr+wrt6ds4HaMw23TP612fEyGekRE6LNRiLYr/aqbHXNedw==", + "dev": true + }, "union-value": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/union-value/-/union-value-1.0.1.tgz", diff --git a/node_sdk/package.json b/node_sdk/package.json index 2cde58c..f08c361 100644 --- a/node_sdk/package.json +++ b/node_sdk/package.json @@ -80,7 +80,7 @@ "rimraf": "^3.0.2", "ts-jest": "^26.4.0", "ts-protoc-gen": "^0.13.0", - "typedoc": "^0.19.2", + "typedoc": "0.17.0-3", "typescript": "^4.0.3" } } diff --git a/pkg/protos/markdown.tmpl b/pkg/protos/markdown.tmpl index 751c420..e4dcd10 100644 --- a/pkg/protos/markdown.tmpl +++ b/pkg/protos/markdown.tmpl @@ -1,3 +1,16 @@ +{{- define "TypeLink"}}{{with trimPrefix "." . -}} +[{{.}}]({{$service_name := . | regexFind "^[a-z0-9_]+\\." | trimSuffix "." -}} + {{if len $service_name -}} + {{if hasPrefix "google" $service_name -}} + https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#{{.}} + {{- else -}} + {{$service_name}}_service.html#{{. | trimPrefix (print $service_name ".") | lower | replace "." ""}} + {{- end -}} + {{- else -}} + #{{. | lower | replace "." ""}}{{end}}) + {{- end -}} +{{- end -}} + {{range .Files}} {{- $file_name := .Name -}} # {{(index .Services 0).Name | trimSuffix "Service"}} Service @@ -8,17 +21,17 @@ Protobuf definition: [{{.Name}}](https://github.com/SouthbankSoftware/proofable/ ## Table of Contents {{- if .Services -}} {{range .Services}} -- [{{.Name}}](#{{lower .LongName | replace "." ""}}) +- [{{.Name}}](#{{.LongName | lower | replace "." ""}}) {{- end}} {{- end -}} {{- if .Messages -}} {{range .Messages}} -- [{{.LongName}}](#{{lower .LongName | replace "." ""}}) +- [{{.LongName}}](#{{.LongName | lower | replace "." ""}}) {{- end}} {{- end -}} {{- if .Enums -}} {{range .Enums}} -- [{{.LongName}}](#{{lower .LongName | replace "." ""}}) +- [{{.LongName}}](#{{.LongName | lower | replace "." ""}}) {{- end}} {{- end -}} {{- if .Extensions -}} @@ -35,7 +48,7 @@ Protobuf definition: [{{.Name}}](https://github.com/SouthbankSoftware/proofable/ | Method Name | Request Type | Response Type | Description | | ----------- | ------------ | ------------- | ------------| {{range .Methods -}} - | {{.Name}} | [{{.RequestLongType}}](#{{.RequestFullType}}){{if .RequestStreaming}} stream{{end}} | [{{.ResponseLongType}}](#{{.ResponseFullType}}){{if .ResponseStreaming}} stream{{end}} | {{nobr .Description}} | + | {{.Name}} | {{template "TypeLink" .RequestLongType}}{{if .RequestStreaming}} stream{{end}} | {{template "TypeLink" .ResponseLongType}}{{if .ResponseStreaming}} stream{{end}} | {{nobr .Description}} | {{end}} {{end}} @@ -47,7 +60,7 @@ Protobuf definition: [{{.Name}}](https://github.com/SouthbankSoftware/proofable/ | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | {{range .Fields -}} - | {{.Name}} | [{{.LongType}}](#{{.FullType}}) | {{.Label}} | {{if (index .Options "deprecated"|default false)}}**Deprecated.** {{end}}{{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} | + | {{.Name}} | {{template "TypeLink" .LongType}} | {{.Label}} | {{if (index .Options "deprecated"|default false)}}**Deprecated.** {{end}}{{nobr .Description}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}} | {{end}} {{end}}