diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000000..74b7512e04f --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "gh-pages"] + path = gh-pages + url = https://github.com/GoogleCloudPlatform/google-cloud-node.git + branch = gh-pages diff --git a/gh-pages b/gh-pages new file mode 160000 index 00000000000..fbcb81d9ad8 --- /dev/null +++ b/gh-pages @@ -0,0 +1 @@ +Subproject commit fbcb81d9ad824fdc3a99cfc7b8bae4ae42b0ff40 diff --git a/package.json b/package.json index 250af1d5b34..c021a006351 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,7 @@ "name": "google-cloud-node", "private": "true", "devDependencies": { + "array-includes": "^3.0.3", "array-uniq": "^1.0.3", "async": "^2.0.1", "chalk": "^1.1.3", @@ -15,8 +16,10 @@ "is": "^3.1.0", "jscs": "^2.1.1", "jshint": "^2.9.1", + "lodash.camelcase": "^4.3.0", "lodash.flatten": "^4.3.0", "lodash.template": "^4.3.0", + "lodash.upperfirst": "^4.3.1", "mitm": "^1.1.0", "mocha": "^2.5.3", "multiline": "^1.0.2", @@ -26,6 +29,7 @@ "semver": "^5.3.0", "shelljs": "^0.7.3", "string-format-obj": "^1.0.0", + "string-includes": "^2.0.0", "through2": "^2.0.0" }, "scripts": { diff --git a/packages/datastore/src/v1/doc/doc_datastore.js b/packages/datastore/src/v1/doc/doc_datastore.js new file mode 100644 index 00000000000..3ff2ec875f0 --- /dev/null +++ b/packages/datastore/src/v1/doc/doc_datastore.js @@ -0,0 +1,411 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * The request for {@link Datastore.Lookup}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {Object} readOptions + * The options for this lookup request. + * + * This object should have the same structure as [ReadOptions]{@link ReadOptions} + * + * @property {Object[]} keys + * Keys of entities to look up. + * + * This object should have the same structure as [Key]{@link Key} + * + * @class + * @see [google.datastore.v1.LookupRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var LookupRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Datastore.Lookup}. + * + * @property {Object[]} found + * Entities found as `ResultType.FULL` entities. The order of results in this + * field is undefined and has no relation to the order of the keys in the + * input. + * + * This object should have the same structure as [EntityResult]{@link EntityResult} + * + * @property {Object[]} missing + * Entities not found as `ResultType.KEY_ONLY` entities. The order of results + * in this field is undefined and has no relation to the order of the keys + * in the input. + * + * This object should have the same structure as [EntityResult]{@link EntityResult} + * + * @property {Object[]} deferred + * A list of keys that were not looked up due to resource constraints. The + * order of results in this field is undefined and has no relation to the + * order of the keys in the input. + * + * This object should have the same structure as [Key]{@link Key} + * + * @class + * @see [google.datastore.v1.LookupResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var LookupResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Datastore.RunQuery}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {Object} partitionId + * Entities are partitioned into subsets, identified by a partition ID. + * Queries are scoped to a single partition. + * This partition ID is normalized with the standard default context + * partition ID. + * + * This object should have the same structure as [PartitionId]{@link PartitionId} + * + * @property {Object} readOptions + * The options for this query. + * + * This object should have the same structure as [ReadOptions]{@link ReadOptions} + * + * @property {Object} query + * The query to run. + * + * This object should have the same structure as [Query]{@link Query} + * + * @property {Object} gqlQuery + * The GQL query to run. + * + * This object should have the same structure as [GqlQuery]{@link GqlQuery} + * + * @class + * @see [google.datastore.v1.RunQueryRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var RunQueryRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Datastore.RunQuery}. + * + * @property {Object} batch + * A batch of query results (always present). + * + * This object should have the same structure as [QueryResultBatch]{@link QueryResultBatch} + * + * @property {Object} query + * The parsed form of the `GqlQuery` from the request, if it was set. + * + * This object should have the same structure as [Query]{@link Query} + * + * @class + * @see [google.datastore.v1.RunQueryResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var RunQueryResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Datastore.BeginTransaction}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @class + * @see [google.datastore.v1.BeginTransactionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var BeginTransactionRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Datastore.BeginTransaction}. + * + * @property {string} transaction + * The transaction identifier (always present). + * + * @class + * @see [google.datastore.v1.BeginTransactionResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var BeginTransactionResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Datastore.Rollback}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {string} transaction + * The transaction identifier, returned by a call to + * {@link Datastore.BeginTransaction}. + * + * @class + * @see [google.datastore.v1.RollbackRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var RollbackRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Datastore.Rollback}. + * (an empty message). + * @class + * @see [google.datastore.v1.RollbackResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var RollbackResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Datastore.Commit}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {number} mode + * The type of commit to perform. Defaults to `TRANSACTIONAL`. + * + * The number should be among the values of [Mode]{@link Mode} + * + * @property {string} transaction + * The identifier of the transaction associated with the commit. A + * transaction identifier is returned by a call to + * {@link Datastore.BeginTransaction}. + * + * @property {Object[]} mutations + * The mutations to perform. + * + * When mode is `TRANSACTIONAL`, mutations affecting a single entity are + * applied in order. The following sequences of mutations affecting a single + * entity are not permitted in a single `Commit` request: + * + * - `insert` followed by `insert` + * - `update` followed by `insert` + * - `upsert` followed by `insert` + * - `delete` followed by `update` + * + * When mode is `NON_TRANSACTIONAL`, no two mutations may affect a single + * entity. + * + * This object should have the same structure as [Mutation]{@link Mutation} + * + * @class + * @see [google.datastore.v1.CommitRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var CommitRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The modes available for commits. + * + * @enum {number} + */ + Mode: { + + /** + * Unspecified. This value must not be used. + */ + MODE_UNSPECIFIED: 0, + + /** + * Transactional: The mutations are either all applied, or none are applied. + * Learn about transactions [here](https://cloud.google.com/datastore/docs/concepts/transactions). + */ + TRANSACTIONAL: 1, + + /** + * Non-transactional: The mutations may not apply as all or none. + */ + NON_TRANSACTIONAL: 2 + } +}; + +/** + * The response for {@link Datastore.Commit}. + * + * @property {Object[]} mutationResults + * The result of performing the mutations. + * The i-th mutation result corresponds to the i-th mutation in the request. + * + * This object should have the same structure as [MutationResult]{@link MutationResult} + * + * @property {number} indexUpdates + * The number of index entries updated during the commit, or zero if none were + * updated. + * + * @class + * @see [google.datastore.v1.CommitResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var CommitResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for {@link Datastore.AllocateIds}. + * + * @property {string} projectId + * The ID of the project against which to make the request. + * + * @property {Object[]} keys + * A list of keys with incomplete key paths for which to allocate IDs. + * No key may be reserved/read-only. + * + * This object should have the same structure as [Key]{@link Key} + * + * @class + * @see [google.datastore.v1.AllocateIdsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var AllocateIdsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for {@link Datastore.AllocateIds}. + * + * @property {Object[]} keys + * The keys specified in the request (in the same order), each with + * its key path completed with a newly allocated ID. + * + * This object should have the same structure as [Key]{@link Key} + * + * @class + * @see [google.datastore.v1.AllocateIdsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var AllocateIdsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A mutation to apply to an entity. + * + * @property {Object} insert + * The entity to insert. The entity must not already exist. + * The entity key's final path element may be incomplete. + * + * This object should have the same structure as [Entity]{@link Entity} + * + * @property {Object} update + * The entity to update. The entity must already exist. + * Must have a complete key path. + * + * This object should have the same structure as [Entity]{@link Entity} + * + * @property {Object} upsert + * The entity to upsert. The entity may or may not already exist. + * The entity key's final path element may be incomplete. + * + * This object should have the same structure as [Entity]{@link Entity} + * + * @property {Object} delete + * The key of the entity to delete. The entity may or may not already exist. + * Must have a complete key path and must not be reserved/read-only. + * + * This object should have the same structure as [Key]{@link Key} + * + * @property {number} baseVersion + * The version of the entity that this mutation is being applied to. If this + * does not match the current version on the server, the mutation conflicts. + * + * @class + * @see [google.datastore.v1.Mutation definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var Mutation = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The result of applying a mutation. + * + * @property {Object} key + * The automatically allocated key. + * Set only when the mutation allocated a key. + * + * This object should have the same structure as [Key]{@link Key} + * + * @property {number} version + * The version of the entity on the server after processing the mutation. If + * the mutation doesn't change anything on the server, then the version will + * be the version of the current entity or, if no entity is present, a version + * that is strictly greater than the version of any previous entity and less + * than the version of any possible future entity. + * + * @property {boolean} conflictDetected + * Whether a conflict was detected for this mutation. Always false when a + * conflict detection strategy field is not set in the mutation. + * + * @class + * @see [google.datastore.v1.MutationResult definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var MutationResult = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The options shared by read requests. + * + * @property {number} readConsistency + * The non-transactional read consistency to use. + * Cannot be set to `STRONG` for global queries. + * + * The number should be among the values of [ReadConsistency]{@link ReadConsistency} + * + * @property {string} transaction + * The identifier of the transaction in which to read. A + * transaction identifier is returned by a call to + * {@link Datastore.BeginTransaction}. + * + * @class + * @see [google.datastore.v1.ReadOptions definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/datastore.proto} + */ +var ReadOptions = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The possible values for read consistencies. + * + * @enum {number} + */ + ReadConsistency: { + + /** + * Unspecified. This value must not be used. + */ + READ_CONSISTENCY_UNSPECIFIED: 0, + + /** + * Strong consistency. + */ + STRONG: 1, + + /** + * Eventual consistency. + */ + EVENTUAL: 2 + } +}; \ No newline at end of file diff --git a/packages/datastore/src/v1/doc/doc_entity.js b/packages/datastore/src/v1/doc/doc_entity.js new file mode 100644 index 00000000000..33ae665f9da --- /dev/null +++ b/packages/datastore/src/v1/doc/doc_entity.js @@ -0,0 +1,250 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * A partition ID identifies a grouping of entities. The grouping is always + * by project and namespace, however the namespace ID may be empty. + * + * A partition ID contains several dimensions: + * project ID and namespace ID. + * + * Partition dimensions: + * + * - May be `""`. + * - Must be valid UTF-8 bytes. + * - Must have values that match regex `[A-Za-z\d\.\-_]{1,100}` + * If the value of any dimension matches regex `__.*__`, the partition is + * reserved/read-only. + * A reserved/read-only partition ID is forbidden in certain documented + * contexts. + * + * Foreign partition IDs (in which the project ID does + * not match the context project ID ) are discouraged. + * Reads and writes of foreign partition IDs may fail if the project is not in an active state. + * + * @property {string} projectId + * The ID of the project to which the entities belong. + * + * @property {string} namespaceId + * If not empty, the ID of the namespace to which the entities belong. + * + * @class + * @see [google.datastore.v1.PartitionId definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ +var PartitionId = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A unique identifier for an entity. + * If a key's partition ID or any of its path kinds or names are + * reserved/read-only, the key is reserved/read-only. + * A reserved/read-only key is forbidden in certain documented contexts. + * + * @property {Object} partitionId + * Entities are partitioned into subsets, currently identified by a project + * ID and namespace ID. + * Queries are scoped to a single partition. + * + * This object should have the same structure as [PartitionId]{@link PartitionId} + * + * @property {Object[]} path + * The entity path. + * An entity path consists of one or more elements composed of a kind and a + * string or numerical identifier, which identify entities. The first + * element identifies a _root entity_, the second element identifies + * a _child_ of the root entity, the third element identifies a child of the + * second entity, and so forth. The entities identified by all prefixes of + * the path are called the element's _ancestors_. + * + * An entity path is always fully complete: *all* of the entity's ancestors + * are required to be in the path along with the entity identifier itself. + * The only exception is that in some documented cases, the identifier in the + * last path element (for the entity) itself may be omitted. For example, + * the last path element of the key of `Mutation.insert` may have no + * identifier. + * + * A path can never be empty, and a path can have at most 100 elements. + * + * This object should have the same structure as [PathElement]{@link PathElement} + * + * @class + * @see [google.datastore.v1.Key definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ +var Key = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A (kind, ID/name) pair used to construct a key path. + * + * If either name or ID is set, the element is complete. + * If neither is set, the element is incomplete. + * + * @property {string} kind + * The kind of the entity. + * A kind matching regex `__.*__` is reserved/read-only. + * A kind must not contain more than 1500 bytes when UTF-8 encoded. + * Cannot be `""`. + * + * @property {number} id + * The auto-allocated ID of the entity. + * Never equal to zero. Values less than zero are discouraged and may not + * be supported in the future. + * + * @property {string} name + * The name of the entity. + * A name matching regex `__.*__` is reserved/read-only. + * A name must not be more than 1500 bytes when UTF-8 encoded. + * Cannot be `""`. + * + * @class + * @see [google.datastore.v1.Key.PathElement definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ + PathElement: { + // This is for documentation. Actual contents will be loaded by gRPC. + } +}; + +/** + * An array value. + * + * @property {Object[]} values + * Values in the array. + * The order of this array may not be preserved if it contains a mix of + * indexed and unindexed values. + * + * This object should have the same structure as [Value]{@link Value} + * + * @class + * @see [google.datastore.v1.ArrayValue definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ +var ArrayValue = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A message that can hold any of the supported value types and associated + * metadata. + * + * @property {number} nullValue + * A null value. + * + * The number should be among the values of [google.protobuf.NullValue]{@link external:"google.protobuf.NullValue"} + * + * @property {boolean} booleanValue + * A boolean value. + * + * @property {number} integerValue + * An integer value. + * + * @property {number} doubleValue + * A double value. + * + * @property {Object} timestampValue + * A timestamp value. + * When stored in the Datastore, precise only to microseconds; + * any additional precision is rounded down. + * + * This object should have the same structure as [google.protobuf.Timestamp]{@link external:"google.protobuf.Timestamp"} + * + * @property {Object} keyValue + * A key value. + * + * This object should have the same structure as [Key]{@link Key} + * + * @property {string} stringValue + * A UTF-8 encoded string value. + * When `exclude_from_indexes` is false (it is indexed) , may have at most 1500 bytes. + * Otherwise, may be set to at least 1,000,000 bytes. + * + * @property {string} blobValue + * A blob value. + * May have at most 1,000,000 bytes. + * When `exclude_from_indexes` is false, may have at most 1500 bytes. + * In JSON requests, must be base64-encoded. + * + * @property {Object} geoPointValue + * A geo point value representing a point on the surface of Earth. + * + * This object should have the same structure as [google.type.LatLng]{@link external:"google.type.LatLng"} + * + * @property {Object} entityValue + * An entity value. + * + * - May have no key. + * - May have a key with an incomplete key path. + * - May have a reserved/read-only key. + * + * This object should have the same structure as [Entity]{@link Entity} + * + * @property {Object} arrayValue + * An array value. + * Cannot contain another array value. + * A `Value` instance that sets field `array_value` must not set fields + * `meaning` or `exclude_from_indexes`. + * + * This object should have the same structure as [ArrayValue]{@link ArrayValue} + * + * @property {number} meaning + * The `meaning` field should only be populated for backwards compatibility. + * + * @property {boolean} excludeFromIndexes + * If the value should be excluded from all indexes including those defined + * explicitly. + * + * @class + * @see [google.datastore.v1.Value definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ +var Value = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A Datastore data object. + * + * An entity is limited to 1 megabyte when stored. That _roughly_ + * corresponds to a limit of 1 megabyte for the serialized form of this + * message. + * + * @property {Object} key + * The entity's key. + * + * An entity must have a key, unless otherwise documented (for example, + * an entity in `Value.entity_value` may have no key). + * An entity's kind is its key path's last element's kind, + * or null if it has no key. + * + * This object should have the same structure as [Key]{@link Key} + * + * @property {Object.} properties + * The entity's properties. + * The map's keys are property names. + * A property name matching regex `__.*__` is reserved. + * A reserved property name is forbidden in certain documented contexts. + * The name must not contain more than 500 characters. + * The name cannot be `""`. + * + * @class + * @see [google.datastore.v1.Entity definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/entity.proto} + */ +var Entity = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/packages/datastore/src/v1/doc/doc_google_protobuf_wrappers.js b/packages/datastore/src/v1/doc/doc_google_protobuf_wrappers.js new file mode 100644 index 00000000000..46a5e3e2213 --- /dev/null +++ b/packages/datastore/src/v1/doc/doc_google_protobuf_wrappers.js @@ -0,0 +1,128 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * Wrapper message for `double`. + * + * The JSON representation for `DoubleValue` is JSON number. + * + * @external "google.protobuf.DoubleValue" + * @property {number} value + * The double value. + * + * @see [google.protobuf.DoubleValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `float`. + * + * The JSON representation for `FloatValue` is JSON number. + * + * @external "google.protobuf.FloatValue" + * @property {number} value + * The float value. + * + * @see [google.protobuf.FloatValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `int64`. + * + * The JSON representation for `Int64Value` is JSON string. + * + * @external "google.protobuf.Int64Value" + * @property {number} value + * The int64 value. + * + * @see [google.protobuf.Int64Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `uint64`. + * + * The JSON representation for `UInt64Value` is JSON string. + * + * @external "google.protobuf.UInt64Value" + * @property {number} value + * The uint64 value. + * + * @see [google.protobuf.UInt64Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `int32`. + * + * The JSON representation for `Int32Value` is JSON number. + * + * @external "google.protobuf.Int32Value" + * @property {number} value + * The int32 value. + * + * @see [google.protobuf.Int32Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `uint32`. + * + * The JSON representation for `UInt32Value` is JSON number. + * + * @external "google.protobuf.UInt32Value" + * @property {number} value + * The uint32 value. + * + * @see [google.protobuf.UInt32Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `bool`. + * + * The JSON representation for `BoolValue` is JSON `true` and `false`. + * + * @external "google.protobuf.BoolValue" + * @property {boolean} value + * The bool value. + * + * @see [google.protobuf.BoolValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `string`. + * + * The JSON representation for `StringValue` is JSON string. + * + * @external "google.protobuf.StringValue" + * @property {string} value + * The string value. + * + * @see [google.protobuf.StringValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ + +/** + * Wrapper message for `bytes`. + * + * The JSON representation for `BytesValue` is JSON string. + * + * @external "google.protobuf.BytesValue" + * @property {string} value + * The bytes value. + * + * @see [google.protobuf.BytesValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ \ No newline at end of file diff --git a/packages/datastore/src/v1/doc/doc_query.js b/packages/datastore/src/v1/doc/doc_query.js new file mode 100644 index 00000000000..90c44904ce8 --- /dev/null +++ b/packages/datastore/src/v1/doc/doc_query.js @@ -0,0 +1,489 @@ +/* + * Copyright 2017, Google Inc. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * Note: this file is purely for documentation. Any contents are not expected + * to be loaded as the JS file. + */ + +/** + * The result of fetching an entity from Datastore. + * + * @property {Object} entity + * The resulting entity. + * + * This object should have the same structure as [Entity]{@link Entity} + * + * @property {number} version + * The version of the entity, a strictly positive number that monotonically + * increases with changes to the entity. + * + * This field is set for {@link `FULL`} entity + * results. + * + * For {@link missing} entities in `LookupResponse`, this + * is the version of the snapshot that was used to look up the entity, and it + * is always set except for eventually consistent reads. + * + * @property {string} cursor + * A cursor that points to the position after the result entity. + * Set only when the `EntityResult` is part of a `QueryResultBatch` message. + * + * @class + * @see [google.datastore.v1.EntityResult definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var EntityResult = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Specifies what data the 'entity' field contains. + * A `ResultType` is either implied (for example, in `LookupResponse.missing` + * from `datastore.proto`, it is always `KEY_ONLY`) or specified by context + * (for example, in message `QueryResultBatch`, field `entity_result_type` + * specifies a `ResultType` for all the values in field `entity_results`). + * + * @enum {number} + */ + ResultType: { + + /** + * Unspecified. This value is never used. + */ + RESULT_TYPE_UNSPECIFIED: 0, + + /** + * The key and properties. + */ + FULL: 1, + + /** + * A projected subset of properties. The entity may have no key. + */ + PROJECTION: 2, + + /** + * Only the key. + */ + KEY_ONLY: 3 + } +}; + +/** + * A query for entities. + * + * @property {Object[]} projection + * The projection to return. Defaults to returning all properties. + * + * This object should have the same structure as [Projection]{@link Projection} + * + * @property {Object[]} kind + * The kinds to query (if empty, returns entities of all kinds). + * Currently at most 1 kind may be specified. + * + * This object should have the same structure as [KindExpression]{@link KindExpression} + * + * @property {Object} filter + * The filter to apply. + * + * This object should have the same structure as [Filter]{@link Filter} + * + * @property {Object[]} order + * The order to apply to the query results (if empty, order is unspecified). + * + * This object should have the same structure as [PropertyOrder]{@link PropertyOrder} + * + * @property {Object[]} distinctOn + * The properties to make distinct. The query results will contain the first + * result for each distinct combination of values for the given properties + * (if empty, all results are returned). + * + * This object should have the same structure as [PropertyReference]{@link PropertyReference} + * + * @property {string} startCursor + * A starting point for the query results. Query cursors are + * returned in query result batches and + * [can only be used to continue the same query](https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets). + * + * @property {string} endCursor + * An ending point for the query results. Query cursors are + * returned in query result batches and + * [can only be used to limit the same query](https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets). + * + * @property {number} offset + * The number of results to skip. Applies before limit, but after all other + * constraints. Optional. Must be >= 0 if specified. + * + * @property {Object} limit + * The maximum number of results to return. Applies after all other + * constraints. Optional. + * Unspecified is interpreted as no limit. + * Must be >= 0 if specified. + * + * This object should have the same structure as [google.protobuf.Int32Value]{@link external:"google.protobuf.Int32Value"} + * + * @class + * @see [google.datastore.v1.Query definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var Query = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A representation of a kind. + * + * @property {string} name + * The name of the kind. + * + * @class + * @see [google.datastore.v1.KindExpression definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var KindExpression = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A reference to a property relative to the kind expressions. + * + * @property {string} name + * The name of the property. + * If name includes "."s, it may be interpreted as a property name path. + * + * @class + * @see [google.datastore.v1.PropertyReference definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var PropertyReference = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A representation of a property in a projection. + * + * @property {Object} property + * The property to project. + * + * This object should have the same structure as [PropertyReference]{@link PropertyReference} + * + * @class + * @see [google.datastore.v1.Projection definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var Projection = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The desired order for a specific property. + * + * @property {Object} property + * The property to order by. + * + * This object should have the same structure as [PropertyReference]{@link PropertyReference} + * + * @property {number} direction + * The direction to order by. Defaults to `ASCENDING`. + * + * The number should be among the values of [Direction]{@link Direction} + * + * @class + * @see [google.datastore.v1.PropertyOrder definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var PropertyOrder = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The sort direction. + * + * @enum {number} + */ + Direction: { + + /** + * Unspecified. This value must not be used. + */ + DIRECTION_UNSPECIFIED: 0, + + /** + * Ascending. + */ + ASCENDING: 1, + + /** + * Descending. + */ + DESCENDING: 2 + } +}; + +/** + * A holder for any type of filter. + * + * @property {Object} compositeFilter + * A composite filter. + * + * This object should have the same structure as [CompositeFilter]{@link CompositeFilter} + * + * @property {Object} propertyFilter + * A filter on a property. + * + * This object should have the same structure as [PropertyFilter]{@link PropertyFilter} + * + * @class + * @see [google.datastore.v1.Filter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var Filter = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A filter that merges multiple other filters using the given operator. + * + * @property {number} op + * The operator for combining multiple filters. + * + * The number should be among the values of [Operator]{@link Operator} + * + * @property {Object[]} filters + * The list of filters to combine. + * Must contain at least one filter. + * + * This object should have the same structure as [Filter]{@link Filter} + * + * @class + * @see [google.datastore.v1.CompositeFilter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var CompositeFilter = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A composite filter operator. + * + * @enum {number} + */ + Operator: { + + /** + * Unspecified. This value must not be used. + */ + OPERATOR_UNSPECIFIED: 0, + + /** + * The results are required to satisfy each of the combined filters. + */ + AND: 1 + } +}; + +/** + * A filter on a specific property. + * + * @property {Object} property + * The property to filter by. + * + * This object should have the same structure as [PropertyReference]{@link PropertyReference} + * + * @property {number} op + * The operator to filter by. + * + * The number should be among the values of [Operator]{@link Operator} + * + * @property {Object} value + * The value to compare the property to. + * + * This object should have the same structure as [Value]{@link Value} + * + * @class + * @see [google.datastore.v1.PropertyFilter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var PropertyFilter = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A property filter operator. + * + * @enum {number} + */ + Operator: { + + /** + * Unspecified. This value must not be used. + */ + OPERATOR_UNSPECIFIED: 0, + + /** + * Less than. + */ + LESS_THAN: 1, + + /** + * Less than or equal. + */ + LESS_THAN_OR_EQUAL: 2, + + /** + * Greater than. + */ + GREATER_THAN: 3, + + /** + * Greater than or equal. + */ + GREATER_THAN_OR_EQUAL: 4, + + /** + * Equal. + */ + EQUAL: 5, + + /** + * Has ancestor. + */ + HAS_ANCESTOR: 11 + } +}; + +/** + * A [GQL query](https://cloud.google.com/datastore/docs/apis/gql/gql_reference). + * + * @property {string} queryString + * A string of the format described + * [here](https://cloud.google.com/datastore/docs/apis/gql/gql_reference). + * + * @property {boolean} allowLiterals + * When false, the query string must not contain any literals and instead must + * bind all values. For example, + * `SELECT * FROM Kind WHERE a = 'string literal'` is not allowed, while + * `SELECT * FROM Kind WHERE a = @value` is. + * + * @property {Object.} namedBindings + * For each non-reserved named binding site in the query string, there must be + * a named parameter with that name, but not necessarily the inverse. + * + * Key must match regex `[A-Za-z_$][A-Za-z_$0-9]*`, must not match regex + * `__.*__`, and must not be `""`. + * + * @property {Object[]} positionalBindings + * Numbered binding site @1 references the first numbered parameter, + * effectively using 1-based indexing, rather than the usual 0. + * + * For each binding site numbered i in `query_string`, there must be an i-th + * numbered parameter. The inverse must also be true. + * + * This object should have the same structure as [GqlQueryParameter]{@link GqlQueryParameter} + * + * @class + * @see [google.datastore.v1.GqlQuery definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var GqlQuery = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A binding parameter for a GQL query. + * + * @property {Object} value + * A value parameter. + * + * This object should have the same structure as [Value]{@link Value} + * + * @property {string} cursor + * A query cursor. Query cursors are returned in query + * result batches. + * + * @class + * @see [google.datastore.v1.GqlQueryParameter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var GqlQueryParameter = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A batch of results produced by a query. + * + * @property {number} skippedResults + * The number of results skipped, typically because of an offset. + * + * @property {string} skippedCursor + * A cursor that points to the position after the last skipped result. + * Will be set when `skipped_results` != 0. + * + * @property {number} entityResultType + * The result type for every entity in `entity_results`. + * + * The number should be among the values of [ResultType]{@link ResultType} + * + * @property {Object[]} entityResults + * The results for this batch. + * + * This object should have the same structure as [EntityResult]{@link EntityResult} + * + * @property {string} endCursor + * A cursor that points to the position after the last result in the batch. + * + * @property {number} moreResults + * The state of the query after the current batch. + * + * The number should be among the values of [MoreResultsType]{@link MoreResultsType} + * + * @property {number} snapshotVersion + * The version number of the snapshot this batch was returned from. + * This applies to the range of results from the query's `start_cursor` (or + * the beginning of the query if no cursor was given) to this batch's + * `end_cursor` (not the query's `end_cursor`). + * + * In a single transaction, subsequent query result batches for the same query + * can have a greater snapshot version number. Each batch's snapshot version + * is valid for all preceding batches. + * The value will be zero for eventually consistent queries. + * + * @class + * @see [google.datastore.v1.QueryResultBatch definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/datastore/v1/query.proto} + */ +var QueryResultBatch = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The possible values for the `more_results` field. + * + * @enum {number} + */ + MoreResultsType: { + + /** + * Unspecified. This value is never used. + */ + MORE_RESULTS_TYPE_UNSPECIFIED: 0, + + /** + * There may be additional batches to fetch from this query. + */ + NOT_FINISHED: 1, + + /** + * The query is finished, but there may be more results after the limit. + */ + MORE_RESULTS_AFTER_LIMIT: 2, + + /** + * The query is finished, but there may be more results after the end + * cursor. + */ + MORE_RESULTS_AFTER_CURSOR: 4, + + /** + * The query has been exhausted. + */ + NO_MORE_RESULTS: 3 + } +}; \ No newline at end of file diff --git a/scripts/docs/builder.js b/scripts/docs/builder.js index 08689bd6306..70c14f6c6a8 100644 --- a/scripts/docs/builder.js +++ b/scripts/docs/builder.js @@ -22,8 +22,10 @@ var chalk = require('chalk'); var flatten = require('lodash.flatten'); var fs = require('fs'); var globby = require('globby'); +var is = require('is'); var path = require('path'); var semver = require('semver'); +var stringIncludes = require('string-includes'); var config = require('./config'); var helpers = require('../helpers'); @@ -76,7 +78,13 @@ Builder.prototype.build = function() { mkdir('-p', this.dir); cp(MARKDOWN, this.dir); - var docs = globby.sync(path.join(this.name, 'src/*.js'), { + var docsPaths = [ + path.join(this.name, 'src/*.js'), + path.join(this.name, 'src/**/v*/doc/*.js'), + path.join(this.name, 'src/**/v*/*_client.js') + ]; + + var docs = globby.sync(docsPaths, { cwd: PACKAGES_ROOT, ignore: config.IGNORE }).map(function(file) { @@ -89,6 +97,130 @@ Builder.prototype.build = function() { return json; }); + + var gapicVersions = docs.reduce((grouped, doc) => { + var gapicVersion = doc.id.match(/[/_](v[^\/]*)/); + + if (gapicVersion) { + gapicVersion = gapicVersion[1]; + mkdir('-p', `${self.dir}/${gapicVersion}`); + + if (stringIncludes(doc.id, 'doc_')) { + grouped[gapicVersion] = grouped[gapicVersion] || []; + grouped[gapicVersion].push(doc); + } else if (stringIncludes(doc.id, '_client')) { + // Move client file to a separate path. + doc.path = `${gapicVersion}/${doc.path}`; + self.write(doc.path, doc); + } + } + + return grouped; + }, {}); + + // @TODO delete extra files + docs = docs.filter(doc => !stringIncludes(doc.source, 'doc_')); + + for (var gapicVersion in gapicVersions) { + var gapicFiles = gapicVersions[gapicVersion]; + + this.write(`${gapicVersion}/index.json`, { + name: gapicVersion, + methods: [], + path: `${gapicVersion}/index.json`, + description: ` +

{{docs.services[0].title}} API Contents

+ + + + + + + + + + + + + + + + + + +
ClassDescription
+ {{client.title}} + + Create a {{client.title}} to interact with the {{docs.services[0].title}} API. +
+ Data Types + + Data types for {{docs.services[0].title}} {{service.path.split('/').shift()}}. +
+ ` + }); + + var dataTypesFile = { + name: 'Data Types', + methods: [], + path: `${gapicVersion}/data_types.json`, + description: ` + + + + + + + + + + + + + +
ClassDescription
+ + {{method.name}} + + + + {{method.description}} + + + The request for {{method.name}}. + + + The response for {{method.name}}. + +
+ ` + }; + + /*jshint loopfunc:true*/ + gapicFiles.forEach(gapicFile => { + if (!dataTypesFile.id) { + var idParts = gapicFile.id.split('/'); + idParts.pop(); + idParts.pop(); + idParts.push('data_types'); + dataTypesFile.id = idParts.join('/'); + } + + dataTypesFile.methods = dataTypesFile.methods.concat(gapicFile.methods); + }); + + if (!is.empty(dataTypesFile.methods)) { + this.write(`${gapicVersion}/data_types.json`, dataTypesFile); + docs.push(dataTypesFile); + } + } + var types = parser.createTypesDictionary(docs); var toc = parser.createToc(types); diff --git a/scripts/docs/parser.js b/scripts/docs/parser.js index 20c4a8fde3a..dbe992081d3 100644 --- a/scripts/docs/parser.js +++ b/scripts/docs/parser.js @@ -16,14 +16,19 @@ 'use strict'; +var arrayIncludes = require('array-includes'); +var camel = require('lodash.camelcase'); var dox = require('dox'); -var globby = require('globby'); var fs = require('fs'); -var path = require('path'); +var extend = require('extend'); var format = require('string-format-obj'); +var globby = require('globby'); +var path = require('path'); var prop = require('propprop'); -var extend = require('extend'); +var stringIncludes = require('string-includes'); var template = require('lodash.template'); +var upperFirst = require('lodash.upperfirst'); + var config = require('./config'); var baseToc = require('./templates/toc.json'); @@ -42,17 +47,28 @@ function isMethod(block) { } function detectLinks(str) { + var linkInsideLink = /@link /g; var reg = /\[([^\]]*)]{@link ([^}]*)}/g; - return str.replace(reg, function(match, title, link) { - return '' + title.trim() + ''; - }); + return str + .replace(linkInsideLink, function(match, link) { + return `@link ${link}`; + }) + .replace(reg, function(match, title, link) { + if (link.startsWith('external')) { + return title; + } + + link = link.replace('' + title.trim() + ''; + }); } function formatHtml(html) { var formatted = (html || '') .replace(/\s+/g, ' ') - .replace(/
/g, ' ') + .replace(/
/g, ' ') /* TODO: remove. fixing a sublime text bug */ .replace(/`([^`]*)`/g, '$1'); return detectLinks(detectCustomType(formatted)); @@ -63,6 +79,7 @@ function detectCustomType(str) { var templateFn = format.bind(null, tmpl); var rCustomType = /\{*module\:([^\}|\>]*)\}*/g; var rArray = /Array\.<(.+)>/g; + var rProtoType = /\[\w+\]{@link ([A-Z][^}]*)}/g; return str .replace(rArray, function(match, module) { @@ -76,6 +93,15 @@ function detectCustomType(str) { method: parts[1] || '', text: module }); + }) + // @TODO link-ability + .replace(rProtoType, function(match, protoType) { + return ` + ${protoType} + `.trim(); }); } @@ -158,6 +184,14 @@ function getMethodType(block) { return 'constructor'; } + if (block.ctx) { + var name = block.ctx.name; + + if (/^[A-Z]/.test(name) && name.endsWith('Client')) { + return 'constructor'; + } + } + if (getTagsByType(block, 'static').length > 0) { return 'static'; } @@ -251,6 +285,20 @@ function createReturn(tag) { function createMethod(fileName, parent, block) { var name = getName(block); + var allParams = getTagsByType(block, 'param') + .concat(getTagsByType(block, 'property')) + .map(createParam); + + var isGapic = stringIncludes(fileName, 'doc_'); + var isRequestOrResponse = name && + (stringIncludes(name, 'Request') || stringIncludes(name, 'Response')); + + if (isGapic && isRequestOrResponse) { + // Ignore descriptions that have links we don't want, e.g. + // "The request for {@link Datastore.AllocateIds}." + block.description = {}; + } + return { id: name, name: name, @@ -259,7 +307,7 @@ function createMethod(fileName, parent, block) { source: path.normalize(fileName) + '#L' + block.codeStart, resources: getTagsByType(block, 'resource').map(createResource), examples: createExamples(block), - params: getTagsByType(block, 'param').map(createParam), + params: allParams, exceptions: getTagsByType(block, 'throws').map(createException), returns: getTagsByType(block, 'return').map(createReturn) }; @@ -315,30 +363,85 @@ function parseFile(fileName, contents, umbrellaMode) { } function createTypesDictionary(docs) { - return docs.map(function(service) { + var types = []; + var gapicVersions = []; + + docs.forEach(function(service) { + var isGapic = /_client$/.test(service.id); + + var titleParts = []; var id = service.id; - var title = [id === config.UMBRELLA_PACKAGE ? 'Google Cloud' : service.name]; var contents = service.path; + if (id === config.UMBRELLA_PACKAGE) { + titleParts.push('Google Cloud'); + } else { + titleParts.push(service.name); + } + + if (isGapic) { + var gapicVersion; + var gapicPath = service.id.split('/'); + var versionIndex; + + gapicPath.forEach(function(gapicPathPart, index) { + if (/^v\d/.test(gapicPathPart)) { + gapicVersion = gapicPathPart; + versionIndex = index; + } + }); + + if (!arrayIncludes(gapicVersions, gapicVersion)) { + gapicVersions.push(gapicVersion); + } + + titleParts = [gapicVersion]; + + var nestedTitle = [].slice.call(gapicPath, versionIndex + 1); + + if (nestedTitle.length > 0) { + titleParts.push(upperFirst(camel(nestedTitle.join('/')))); + } + } + if (service.parent) { for (var i = 0, l = docs.length; i < l; i++) { if (docs[i].id === service.parent) { - title.unshift(docs[i].name); + titleParts.unshift(docs[i].name); } } } - return { + types.push({ id: id, - title: title, + title: titleParts, contents: contents - }; + }); + }); + + gapicVersions.forEach(gapicVersion => { + types.push({ + id: gapicVersion, + title: [gapicVersion], + contents: `${gapicVersion}/index.json` + }); }); + + return types; } function createToc(types, collapse) { + var PATH_VERSION_REGEX = /\/(v[^/]*)/; + var toc = extend(true, {}, baseToc); + + var generatedTypes = types.filter(type => / v\d/.test(type.title.join(' '))); + var protos = types.filter(type => stringIncludes(type.id, '/doc/')); + var protosGroupedByVersion = {}; + var services = types + .filter(type => !arrayIncludes(generatedTypes, type)) + .filter(type => !arrayIncludes(protos, type)) .map(function(type) { return { type: type.id, @@ -357,6 +460,67 @@ function createToc(types, collapse) { return a.type < b.type ? -1 : a.type > b.type ? 1 : 0; }); + if (protos.length > 0) { + protos.forEach(function(proto) { + var version = proto.id.match(PATH_VERSION_REGEX)[1]; + protosGroupedByVersion[version] = protosGroupedByVersion[version] || []; + protosGroupedByVersion[version].push(proto); + }); + } + + if (generatedTypes.length > 0) { + // Push the generated types to the bottom of the navigation. + var generatedTypesByVersion = {}; + + generatedTypes.forEach(function(generatedType) { + var version = generatedType.title[1]; + generatedTypesByVersion[version] = generatedTypesByVersion[version] || []; + generatedTypesByVersion[version].push(generatedType); + }); + + for (var version in generatedTypesByVersion) { + var generatedTypesGrouped = generatedTypesByVersion[version] + .sort(function(a, b) { + if (a.title.length < b.title.length) { // e.g. ['Spanner', 'v1'] + return -1; + } + + if (b.title.length < a.title.length) { + return 1; + } + + var titleA = a.title[a.title.length - 1]; + var titleB = b.title[b.title.length - 1]; + + return titleA < titleB ? -1 : titleA > titleB ? 1 : 0; + }); + + /*jshint loopfunc:true*/ + services = services.filter(service => service.type !== version); + + var serviceObject = { + title: version, + type: version, + nav: generatedTypesGrouped.map(function(generatedType) { + return { + title: generatedType.title[generatedType.title.length - 1], + type: generatedType.id + }; + }) + }; + + serviceObject.nav.push({ + title: 'Data Types', + type: generatedTypes[0].id.replace(/\/\w+_client$/, '/data_types') + }); + + services.push(serviceObject); + } + } + + services = services + .filter(service => !stringIncludes(service.type, 'data_types')); + if (!collapse) { toc.services = services; return toc; diff --git a/test/docs.js b/test/docs.js index a267202362d..295e8ca3aec 100644 --- a/test/docs.js +++ b/test/docs.js @@ -246,6 +246,8 @@ function getDocs(mod) { return glob .sync('docs/json/' + mod + '/*/*.json', { ignore: [ + '**/doc_*.json', + '**/*_client.json', '**/toc.json', '**/types.json' ]