Writing Reference Docs

Our users depend on having quality documentation for our product. In addition to the prose you should be creating in the istio/istio.io repo, you need to also write quality reference documentation throughout the product.

• Background
• About proto documentation
  • Linking to types and elements
  • Annotations
  • Proto doc checklist
• Hiding content

Background

Our reference documentation comes from five sources:

• Comments on proto files for our config formats and API definitions. The various protos in the istio/api repo, the Mixer adapter configuration and the Mixer template definitions both in the istio/istio repo are all examples of this.

• Cobra commands for our CLI docs. The various CLI commands we build generally use the Cobra framework to parse our command-lines. Cobra is also used to produce reference documentation for the individual commands.

• Environment variables. When code uses environment variables using the istio.io/pkg/env package, these variables are registered and reproduced in our documentation.

• Metrics. The metrics output by individual components are documented to enable users to monitor them.

• Annotations. Kubernetes resource annotations are declared in the istio/api repo and fully documented.

The documentation for the above is provided by developers as part of the normal development process. Comments on protos are scrapped and used in docs. Description strings must be supplied in order to user environment variables, netrics, annotations, and command-line arguments, all of which are used to produce the customer-facing documentation.

About proto documentation

Writing proto documentation is a simple matter of adding comments to elements within the input proto files. You can put comments directly above individual elements, or to the right. For example:

// A package-level comment
package pkg;

// This documents the message as a whole
message MyMsg {
    // This documents this field
    // It can contain many lines.
    int32 field1 = 1;

    int32 field2 = 2;       // This documents field2
}

Comments are treated as markdown. You can thus embed classic markdown annotations within any comment.

Linking to types and elements

In addition to normal markdown links, you can also use special proto links within any comment. Proto links are used to create a link to other types or elements within the set of protos. You specify proto links using two pairs of square brackets such as:

// This is a comment that links to another type: [MyOtherType][MyPkg.MyOtherType]
message MyMsg {

}

The first square brackets contain the name of the type to display in the resulting documentation. The second square brackets contain the fully qualified name of the type or element being referenced, including the package name.

Annotations

Within a proto file, you should insert special comments which provide additional metadata to use in producing quality documentation. Within a package, include an unattached comment of the form:

// $title: My Title
// $overview: My Overview
// $location: https://mysite.com/mypage.html

$title provides a title for the generated package documentation. This is used for things like the title of the generated HTML. $description is a one-line description of the package, useful for tables of contents or indexes. Finally, $location indicates the expected URL for the generated documentation. This is used to help downstream processing tools to know where to copy the documentation, and is used when creating documentation links from other packages to this one.

You can also use any of the annotations known to our web site infrastructure. For example:

// $weight: 10

The above will include the front matter weight: 10 in the generated HTML document.

If a comment for an element contains the annotation $hide_from_docs, then the associated element will be omitted from the output. This is useful when staging the introduction of new features that aren't quite ready for use yet. The annotation can appear anywhere in the comment for the element. For example:

message MyMsg {
    int32 field1 = 1; // $hide_from_docs
}

The comment for any element can contain the annotation $class: <foo> which is used to insert a specific HTML class around the generated element. This is useful to give particular styling to particular elements. Common examples of useful classes include

message MyMsg {
    int32 field1 = 1; // $class: alpha
    int32 field2 = 2; // $class: beta
    int32 field3 = 3; // $class: experimental
}

The specific class used can be used to control the rendering of the element. At the moment, Istio doesn't provide any specific rendering controls for these classes, but it would be easy to add some. As shown in the example, we could readily have different rendering for alpha elements vs. beta vs. experimental. If you find this would be a useful feature, file an issue in istio/istio.github.io to introduce the CSS necessary to support the particular class you want to use.

Proto doc checklist

• Ensure each package contains the appropriate $title, $overview, and $location annotations such that your package's docs are properly published to istio.io.

• Ensure each package contains exactly one package-level comment. This comment is displayed at the top of the documentation page.

• Ensure each element (message, enum, message field, enum value, etc) has good operator-centric documentation.

Hiding content

The different kinds of reference documentation sources support ways to suppress documentation from the final output. This is useful for experimental features not ready for prime-time, for features being deprecated, or for features intended for developer use and not customer use.

As described above, you use the $hide_from_docs annotation in proto files to suppress messages or fields.

For annotations, you set the hidden field to true within annotations.yaml.

For environment variables, you need to register the variable use as hidden.

For command-line options, you use the MarkAsHidden cobra function to indicate a partial option should not be shown to users.