blob: 8749fcd2d666f2b9057b7e93f95ebef4d1d7bddf [file] [log] [blame]
// Copyright 2017 The LUCI Authors. All rights reserved.
// Use of this source code is governed under the Apache License, Version 2.0
// that can be found in the LICENSE file.
syntax = "proto3";
import "recipe_engine/recipes_cfg.proto";
package recipe_engine;
// Doc is the namespace for all documentation messages. The messages here can be
// produced by the 'doc' subcommand.
//
// Messages in this namespace have some common fields:
// name - the name of the object. Unless specified, this is the 'local' name,
// or how you would refer to the object within the file.
// relpath - the forward-slash-delimited path from the root of the repo to
// this documented object.
// lineno - the line number of this documented object within the file. Line
// numbers start from 1.
// docstring - the docstring of the item :). This should be pretty obvious.
// check the comment in cases where it's not.
message Doc {
message Known {
// The url of the repo that this object comes from.
string url = 1;
oneof kind {
Func func = 2;
Class klass = 3; // class is reserved in python
}
message Object {
oneof kind {
// This is a string representation of the object.
string generic = 1;
// This can be looked up in the known_objects map.
string known = 2;
}
}
}
// Schema defines a very simple recursive schema system used by the
// recipe_engine. These correspond to types in the recipe_engine's config.py
// file.
//
// These are named Schema instead of Config because they don't contain any
// values (with the exception of defaults). At some point in the future the
// schema and config concerns will be separated.
message Schema {
// These are the primitive allowed types. They correspond to the types
// allowed by JSON.
enum SimpleType {
STRING = 0;
NUMBER = 1;
BOOLEAN = 2;
OBJECT = 3;
ARRAY = 4;
NULL = 5;
}
// Struct defines a dictionary with a fixed set of keys, each of which has
// a specific schema.
message Struct {
// A mapping of member to schema
map<string, Schema> type_map = 1;
}
// Sequence defines a list of schema'd objects.
//
// Note this is currently equivalent to config.ConfigList.
message Sequence {
Schema inner_type = 1;
}
// List defines a list of simply-typed objects.
message List {
// The simple pythonic type that this list may contain. If specified
// multiple times, the List may contain any of the types.
repeated SimpleType inner_type = 1;
}
// Set defines a set() of simply-typed objects.
message Set {
// The simple pythonic type that this set may contain. If specified
// multiple times, the Set may contain any of the types.
repeated SimpleType inner_type = 1;
}
// Dict defines a mapping of string to simple type.
message Dict {
// The simple pythonic type that this dict may contain as values. If
// specified multiple times, the Dict may contain any of the types.
repeated SimpleType value_type = 1;
}
// Single defines a single value (non-collection) simple type.
message Single {
// The simple pythonic type that this value may contain. If
// specified multiple times, the Single may contain any of the types.
repeated SimpleType inner_type = 1;
// Indicates that omitting this value is an error.
bool required = 2;
// The default value (as JSON) if the value for this is omitted.
string default_json = 3;
}
// Static defines a single static piece of data.
message Static {
// The value of the Static (as JSON).
string default_json = 1;
}
// Enum defines an element of the schema which must be one of a fixed set of
// values.
message Enum {
// The JSON encoded list of accepted values.
repeated string values_json = 1;
// Indicates that omitting this value is an error.
bool required = 2;
}
oneof kind {
Struct struct = 1;
Sequence sequence = 2;
List list = 3;
Set set = 4;
Dict dict = 5;
Single single = 6;
Static static = 7;
Enum enum = 8;
}
}
// Documents one of the `DEPS = [...]` assignments which may show up in
// a recipe file, or in a recipe module's __init__.py file.
message Deps {
string relpath = 1;
int32 lineno = 2;
// A simple tuple of repo_name and module name. This should be enough to
// calculate a link to this module.
message ModuleLink {
string repo_name = 1;
string name = 2;
}
// The list of recipe modules which are named in this Deps (e.g.
// ModuleLink("recipe_engine", "path")).
repeated ModuleLink module_links = 3;
}
// Parameter is the documentation for a single parameter (Property).
message Parameter {
// The docstring (e.g. the help param) of the parameter.
string docstring = 1;
// The schema for the data in this parameter.
Schema kind = 2;
// A JSON string which is the default value for this Parameter. If empty it
// means that this Parameter is required.
string default_json = 3;
}
// Parameters is the documentation for a PROPERTIES dictionary.
message Parameters {
string relpath = 1;
int32 lineno = 2;
// Mapping of parameter name (e.g. what the user would pass in the input
// JSON) to parameter.
map<string, Parameter> parameters = 3;
}
// Documentation for a regular python class.
message Class {
string name = 1;
string relpath = 2;
int32 lineno = 3;
string docstring = 4;
// The list of base classes this class has (if any). A base class may either
// be 'known' or 'generic'. 'known' bases refer to classes defined in the
// known_objects map.
repeated Known.Object bases = 5;
// a mapping of visible inner classes (e.g. class definitions nested within
// this class).
map<string, Class> classes = 6;
// a mapping of visible methods in this class.
map<string, Func> funcs = 7;
}
// Documentation for a regular python function.
message Func {
string name = 1;
string relpath = 2;
int32 lineno = 3;
string docstring = 4;
// The list of decorators this function has (if any). A decorator may either
// be 'known' or 'generic'. 'known' decorators refer to decorators defined
// in the known_objects map.
repeated Known.Object decorators = 5;
// The rendered python ast node for the whole function signature, e.g.:
// "arg, other_arg, default=True, **kwargs"
string signature = 6;
}
// Documentation for a recipe module.
message Module {
// The unqualified name of this recipe module (e.g. "path")
string name = 1;
string relpath = 2;
string docstring = 3;
// The dependencies (other modules) for this module.
Deps deps = 4;
// The PARAMETERS (formerly known as PROPERTIES) for this module.
Parameters parameters = 5;
// The primary class (RecipeApi) for this module.
Class api_class = 6;
// Other classes defined in api.py
map<string, Class> classes = 7;
// Other functions defined in api.py
map<string, Func> funcs = 8;
// The claimed python version compatibility level of this module.
string python_version_compatibility = 9;
}
// Documentation for a recipe.
message Recipe {
reserved 6; // ReturnSchema, was removed
// the name of this recipe within this repo (e.g. 'foo')
string name = 1;
string relpath = 2;
string docstring = 3;
// dependencies (to recipe modules) this recipe has.
Deps deps = 4;
// the documentation for any PARAMETERS this recipe has.
//
// NOTE: these are currently called PROPERTIES, soon to be renamed.
Parameters parameters = 5;
// A mapping of visible class names to class documentation.
map<string, Class> classes = 7;
// A mapping of visible function names to function documentation. Excludes
// GenTests function.
map<string, Func> funcs = 8;
// A map of known items (e.g. core portions of the recipe engine) to their
// documentation.
map<string, Known> known_objects = 9;
// The claimed python version compatibility level of this recipe.
string python_version_compatibility = 10;
}
// Documentation for a recipe repo, including docs for all recipes
// and recipe_module's in that repo.
message Repo {
// This is the name of the repo that's being documented.
string repo_name = 1;
// This is a mapping from repo_name to RepoSpec, including the
// spec for the main repo (as indicated by `repo_name`).
//
// Contains lots of goodies like the path within the repo to where the
// recipes start, and the dependencies of the repos.
map<string, recipe_engine.RepoSpec> specs = 2;
// the full contents of the 'README.recipes.md' file at the base of the repo
// plus recipe_root.
string docstring = 3;
// a map of all of this repo's recipe_module names to their documentation.
map<string, Module> recipe_modules = 4;
// a map of all of this repo's recipe names to their documentation.
map<string, Recipe> recipes = 5;
// A map of known items (e.g. core portions of the recipe engine) to their
// documentation.
map<string, Known> known_objects = 6;
}
}