codekingpro/portable-devtools

1// Copyright 2026 Google LLC2//3// Licensed under the Apache License, Version 2.0 (the "License");4// you may not use this file except in compliance with the License.5// You may obtain a copy of the License at6//7//     http://www.apache.org/licenses/LICENSE-2.08//9// Unless required by applicable law or agreed to in writing, software10// distributed under the License is distributed on an "AS IS" BASIS,11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.12// See the License for the specific language governing permissions and13// limitations under the License.14 15syntax = "proto3";16 17package google.api;18 19option go_package = "google.golang.org/genproto/googleapis/api/serviceconfig;serviceconfig";20option java_multiple_files = true;21option java_outer_classname = "DocumentationProto";22option java_package = "com.google.api";23option objc_class_prefix = "GAPI";24 25// `Documentation` provides the information for describing a service.26//27// Example:28// <pre><code>documentation:29//   summary: >30//     The Google Calendar API gives access31//     to most calendar features.32//   pages:33//   - name: Overview34//     content: &#40;== include google/foo/overview.md ==&#41;35//   - name: Tutorial36//     content: &#40;== include google/foo/tutorial.md ==&#41;37//     subpages:38//     - name: Java39//       content: &#40;== include google/foo/tutorial_java.md ==&#41;40//   rules:41//   - selector: google.calendar.Calendar.Get42//     description: >43//       ...44//   - selector: google.calendar.Calendar.Put45//     description: >46//       ...47// </code></pre>48// Documentation is provided in markdown syntax. In addition to49// standard markdown features, definition lists, tables and fenced50// code blocks are supported. Section headers can be provided and are51// interpreted relative to the section nesting of the context where52// a documentation fragment is embedded.53//54// Documentation from the IDL is merged with documentation defined55// via the config at normalization time, where documentation provided56// by config rules overrides IDL provided.57//58// A number of constructs specific to the API platform are supported59// in documentation text.60//61// In order to reference a proto element, the following62// notation can be used:63// <pre><code>&#91;fully.qualified.proto.name]&#91;]</code></pre>64// To override the display text used for the link, this can be used:65// <pre><code>&#91;display text]&#91;fully.qualified.proto.name]</code></pre>66// Text can be excluded from doc using the following notation:67// <pre><code>&#40;-- internal comment --&#41;</code></pre>68//69// A few directives are available in documentation. Note that70// directives must appear on a single line to be properly71// identified. The `include` directive includes a markdown file from72// an external source:73// <pre><code>&#40;== include path/to/file ==&#41;</code></pre>74// The `resource_for` directive marks a message to be the resource of75// a collection in REST view. If it is not specified, tools attempt76// to infer the resource from the operations in a collection:77// <pre><code>&#40;== resource_for v1.shelves.books ==&#41;</code></pre>78// The directive `suppress_warning` does not directly affect documentation79// and is documented together with service config validation.80message Documentation {81  // A short description of what the service does. The summary must be plain82  // text. It becomes the overview of the service displayed in Google Cloud83  // Console.84  // NOTE: This field is equivalent to the standard field `description`.85  string summary = 1;86 87  // The top level pages for the documentation set.88  repeated Page pages = 5;89 90  // A list of documentation rules that apply to individual API elements.91  //92  // **NOTE:** All service configuration rules follow "last one wins" order.93  repeated DocumentationRule rules = 3;94 95  // The URL to the root of documentation.96  string documentation_root_url = 4;97 98  // Specifies the service root url if the default one (the service name99  // from the yaml file) is not suitable. This can be seen in any fully100  // specified service urls as well as sections that show a base that other101  // urls are relative to.102  string service_root_url = 6;103 104  // Declares a single overview page. For example:105  // <pre><code>documentation:106  //   summary: ...107  //   overview: &#40;== include overview.md ==&#41;108  // </code></pre>109  // This is a shortcut for the following declaration (using pages style):110  // <pre><code>documentation:111  //   summary: ...112  //   pages:113  //   - name: Overview114  //     content: &#40;== include overview.md ==&#41;115  // </code></pre>116  // Note: you cannot specify both `overview` field and `pages` field.117  string overview = 2;118}119 120// A documentation rule provides information about individual API elements.121message DocumentationRule {122  // The selector is a comma-separated list of patterns for any element such as123  // a method, a field, an enum value. Each pattern is a qualified name of the124  // element which may end in "*", indicating a wildcard. Wildcards are only125  // allowed at the end and for a whole component of the qualified name,126  // i.e. "foo.*" is ok, but not "foo.b*" or "foo.*.bar". A wildcard will match127  // one or more components. To specify a default for all applicable elements,128  // the whole pattern "*" is used.129  string selector = 1;130 131  // Description of the selected proto element (e.g. a message, a method, a132  // 'service' definition, or a field). Defaults to leading & trailing comments133  // taken from the proto source definition of the proto element.134  string description = 2;135 136  // Deprecation description of the selected element(s). It can be provided if137  // an element is marked as `deprecated`.138  string deprecation_description = 3;139}140 141// Represents a documentation page. A page can contain subpages to represent142// nested documentation set structure.143message Page {144  // The name of the page. It will be used as an identity of the page to145  // generate URI of the page, text of the link to this page in navigation,146  // etc. The full page name (start from the root page name to this page147  // concatenated with `.`) can be used as reference to the page in your148  // documentation. For example:149  // <pre><code>pages:150  // - name: Tutorial151  //   content: &#40;== include tutorial.md ==&#41;152  //   subpages:153  //   - name: Java154  //     content: &#40;== include tutorial_java.md ==&#41;155  // </code></pre>156  // You can reference `Java` page using Markdown reference link syntax:157  // `[Java][Tutorial.Java]`.158  string name = 1;159 160  // The Markdown content of the page. You can use ```(== include {path}161  // ==)``` to include content from a Markdown file. The content can be used162  // to produce the documentation page such as HTML format page.163  string content = 2;164 165  // Subpages of this page. The order of subpages specified here will be166  // honored in the generated docset.167  repeated Page subpages = 3;168}169