1"""A helper module for generating documentation for rules_rust""" 2 3def page(name, symbols, header_template = None): 4 """Define a collection of attributes used to generate a page of documentation 5 6 Note, all templates are Velocity files: https://velocity.apache.org/engine/devel/user-guide.html 7 8 Args: 9 name (str): The name of the page 10 symbols (list): A list of symbol names 11 header_template (Label, optional): The label of a `header_template` stardoc attribute 12 13 Returns: 14 tuple: The name of the page with the page content 15 """ 16 return (name, struct( 17 name = name, 18 header_template = header_template, 19 symbols = symbols, 20 )) 21 22# buildifier: disable=unnamed-macro 23def gen_header(page): 24 """Generate a header with a table of contents 25 26 Args: 27 page (struct): A `page` struct 28 """ 29 name = "%s_gen_header_vm" % page.name 30 outs = ["%s_gen_header.vm" % page.name] 31 32 # Set the top level header 33 page_names = [w.capitalize() for w in page.name.split("_")] 34 cmd = [ 35 "echo '<!-- Generated with Stardoc: http://skydoc.bazel.build -->'", 36 "echo '# {}'".format(" ".join(page_names)), 37 "echo ''", 38 ] 39 40 # Add table of contents 41 cmd.extend(["echo '* [{rule}](#{rule})'".format(rule = s) for s in page.symbols]) 42 43 # Render an optional header 44 if page.header_template: 45 cmd.extend([ 46 "echo ''", 47 "cat $(execpath {})".format(page.header_template), 48 ]) 49 srcs = [page.header_template] 50 else: 51 srcs = [] 52 53 native.genrule( 54 name = name, 55 outs = outs, 56 cmd = "{\n" + "\n".join(cmd) + "\n} > $@", 57 srcs = srcs, 58 output_to_bindir = True, 59 ) 60