def main(argv):
if FLAGS.output_dir and FLAGS.output_file:
sys.stderr.write(
'Only one of --output_dir or --output_file can be set.')
sys.exit(1)
if not FLAGS.output_dir:
FLAGS.output_dir = DEFAULT_OUTPUT_DIR
if not FLAGS.output_file:
FLAGS.output_file = DEFAULT_OUTPUT_FILE
bzl_files = argv[1:]
try:
strip_prefix = common.validate_strip_prefix(FLAGS.strip_prefix,
bzl_files)
except common.InputError as err:
print(err.message)
sys.exit(1)
rulesets = []
load_sym_extractor = load_extractor.LoadExtractor()
for bzl_file in bzl_files:
load_symbols = []
try:
load_symbols = load_sym_extractor.extract(bzl_file)
except load_extractor.LoadExtractorError as e:
print("ERROR: Error extracting loaded symbols from %s: %s" %
(bzl_file, str(e)))
sys.exit(2)
# TODO(dzc): Make MacroDocExtractor and RuleDocExtractor stateless.
macro_doc_extractor = macro_extractor.MacroDocExtractor()
rule_doc_extractor = rule_extractor.RuleDocExtractor()
macro_doc_extractor.parse_bzl(bzl_file)
rule_doc_extractor.parse_bzl(bzl_file, load_symbols)
merged_language = merge_languages(macro_doc_extractor.proto(),
rule_doc_extractor.proto())
rulesets.append(
rule.RuleSet(bzl_file, merged_language, macro_doc_extractor.title,
macro_doc_extractor.description, strip_prefix,
FLAGS.format))
writer_options = WriterOptions(FLAGS.output_dir, FLAGS.output_file,
FLAGS.zip, FLAGS.overview,
FLAGS.overview_filename, FLAGS.link_ext)
if FLAGS.format == "markdown":
markdown_writer = MarkdownWriter(writer_options)
markdown_writer.write(rulesets)
elif FLAGS.format == "html":
html_writer = HtmlWriter(writer_options)
html_writer.write(rulesets)
else:
sys.stderr.write(
'Invalid output format: %s. Possible values are markdown and html'
% FLAGS.format)
def test_file_doc_title_only(self):
src = textwrap.dedent("""\
\"\"\"Example rules\"\"\"
""")
with tempfile.NamedTemporaryFile() as tf:
tf.write(src)
tf.flush()
extractor = macro_extractor.MacroDocExtractor()
extractor.parse_bzl(tf.name)
self.assertEqual('Example rules', extractor.title)
self.assertEqual('', extractor.description)
def check_protos(self, src, expected):
with tempfile.NamedTemporaryFile() as tf:
tf.write(src)
tf.flush()
expected_proto = build_pb2.BuildLanguage()
text_format.Merge(expected, expected_proto)
extractor = macro_extractor.MacroDocExtractor()
extractor.parse_bzl(tf.name)
proto = extractor.proto()
self.assertEqual(expected_proto, proto)
def test_file_doc_title_only(self):
src = textwrap.dedent("""\
\"\"\"Example rules\"\"\"
""")
tf = tempfile.NamedTemporaryFile(mode='w+', delete=False)
tf.write(src)
tf.flush()
tf.close()
extractor = macro_extractor.MacroDocExtractor()
extractor.parse_bzl(tf.name)
os.remove(tf.name)
self.assertEqual('Example rules', extractor.title)
self.assertEqual('', extractor.description)
def check_protos(self, src, expected):
tf = tempfile.NamedTemporaryFile(mode='w+', delete=False)
tf.write(src)
tf.flush()
tf.close()
expected_proto = build_pb2.BuildLanguage()
text_format.Merge(expected, expected_proto)
extractor = macro_extractor.MacroDocExtractor()
extractor.parse_bzl(tf.name)
proto = extractor.proto()
os.remove(tf.name)
self.assertEqual(expected_proto, proto)
def test_file_doc_title_description(self):
src = textwrap.dedent("""\
\"\"\"Example rules
This file contains example Bazel rules.
Documentation continued here.
\"\"\"
""")
with tempfile.NamedTemporaryFile() as tf:
tf.write(src)
tf.flush()
extractor = macro_extractor.MacroDocExtractor()
extractor.parse_bzl(tf.name)
self.assertEqual('Example rules', extractor.title)
self.assertEqual(
'This file contains example Bazel rules.'
'\n\nDocumentation continued here.', extractor.description)
def test_file_doc_title_multiline(self):
src = textwrap.dedent("""\
\"\"\"Example rules
for Bazel
This file contains example Bazel rules.
Documentation continued here.
\"\"\"
""")
tf = tempfile.NamedTemporaryFile(mode='w+', delete=False)
tf.write(src)
tf.flush()
tf.close()
extractor = macro_extractor.MacroDocExtractor()
extractor.parse_bzl(tf.name)
os.remove(tf.name)
self.assertEqual('Example rules for Bazel', extractor.title)
self.assertEqual(
'This file contains example Bazel rules.'
'\n\nDocumentation continued here.', extractor.description)
def main(argv):
if FLAGS.output_dir and FLAGS.output_file:
sys.stderr.write(
'Only one of --output_dir or --output_file can be set.')
sys.exit(1)
if not FLAGS.output_dir:
FLAGS.output_dir = DEFAULT_OUTPUT_DIR
if not FLAGS.output_file:
FLAGS.output_file = DEFAULT_OUTPUT_FILE
bzl_files = argv[1:]
try:
strip_prefix = common.validate_strip_prefix(FLAGS.strip_prefix,
bzl_files)
except common.InputError as err:
print(err.message)
sys.exit(1)
runfiles = runfiles_lib.Create()
if not runfiles:
# TODO(laszlocsomor): fix https://github.com/bazelbuild/bazel/issues/6212
# and remove this if-block once Bazel is released with that bugfix.
if (not os.environ.get("RUNFILES_DIR")
and not os.environ.get("RUNFILES_MANIFEST_FILE")):
argv0 = sys.argv[0]
pos = argv0.rfind('%s%s%s' % (os.sep, WORKSPACE_DIR, os.sep))
if pos > -1:
dirpath = argv0[0:pos]
if not os.path.isdir(dirpath):
print("ERROR: Cannot access runfiles directory (%s)" %
dirpath)
sys.exit(1)
runfiles = runfiles_lib.CreateDirectoryBased(dirpath)
if not runfiles:
print("ERROR: Cannot load runfiles")
sys.exit(1)
rulesets = []
load_sym_extractor = load_extractor.LoadExtractor()
for bzl_file in bzl_files:
load_symbols = []
try:
load_symbols = load_sym_extractor.extract(bzl_file)
except load_extractor.LoadExtractorError as e:
print("ERROR: Error extracting loaded symbols from %s: %s" %
(bzl_file, str(e)))
sys.exit(2)
# TODO(dzc): Make MacroDocExtractor and RuleDocExtractor stateless.
macro_doc_extractor = macro_extractor.MacroDocExtractor()
rule_doc_extractor = rule_extractor.RuleDocExtractor()
macro_doc_extractor.parse_bzl(bzl_file)
rule_doc_extractor.parse_bzl(bzl_file, load_symbols)
merged_language = merge_languages(macro_doc_extractor.proto(),
rule_doc_extractor.proto())
rulesets.append(
rule.RuleSet(bzl_file, merged_language, macro_doc_extractor.title,
macro_doc_extractor.description, strip_prefix,
FLAGS.format))
writer_options = WriterOptions(FLAGS.output_dir, FLAGS.output_file,
FLAGS.zip, FLAGS.overview,
FLAGS.overview_filename, FLAGS.link_ext,
FLAGS.site_root)
if FLAGS.format == "markdown":
markdown_writer = MarkdownWriter(writer_options, runfiles)
markdown_writer.write(rulesets)
elif FLAGS.format == "html":
html_writer = HtmlWriter(writer_options, runfiles)
html_writer.write(rulesets)
else:
sys.stderr.write(
'Invalid output format: %s. Possible values are markdown and html'
% FLAGS.format)
def main(argv):
parser = OptionParser()
parser.add_option(
'--output_dir',
default='',
help=
'The directory to write the output generated documentation to if --zip=false'
)
parser.add_option(
'--output_file',
default='',
help='The output zip archive file to write if --zip=true.')
parser.add_option(
'--format',
default='markdown',
help='The output format. Possible values are markdown and html')
parser.add_option(
'--zip',
action='store_true',
default=True,
help='Whether to generate a ZIP arhive containing the output files. If '
'--zip is true, then skydoc will generate a zip file, skydoc.zip by '
'default or as specified by --output_file. If --zip is false, then '
'skydoc will generate documentation, either in Markdown or HTML as '
'specifed by --format, in the current directory or --output_dir if set.'
)
parser.add_option(
'--strip_prefix',
default='',
help='The directory prefix to strip from all generated docs, which are '
'generated in subdirectories that match the package structure of the '
'input .bzl files. The prefix to strip must be common to all .bzl files; '
'otherwise, skydoc will raise an error.')
parser.add_option('--overview',
action='store_true',
help='Whether to generate an overview page')
parser.add_option('--overview_filename',
default='index',
help='The file name to use for the overview page.')
parser.add_option(
'--link_ext',
default='html',
help='The file extension used for links in the generated documentation'
)
parser.add_option(
'--site_root',
default='',
help=
'The site root to be prepended to all URLs in the generated documentation'
)
(options, args) = parser.parse_args(argv)
if options.output_dir and options.output_file:
sys.stderr.write(
'Only one of --output_dir or --output_file can be set.')
sys.exit(1)
if not options.output_dir:
options.output_dir = DEFAULT_OUTPUT_DIR
if not options.output_file:
options.output_file = DEFAULT_OUTPUT_FILE
bzl_files = args[1:]
try:
strip_prefix = common.validate_strip_prefix(options.strip_prefix,
bzl_files)
except common.InputError as err:
print(err.message)
sys.exit(1)
runfiles = runfiles_lib.Create()
if not runfiles:
# TODO(laszlocsomor): fix https://github.com/bazelbuild/bazel/issues/6212
# and remove this if-block once Bazel is released with that bugfix.
if (not os.environ.get("RUNFILES_DIR")
and not os.environ.get("RUNFILES_MANIFEST_FILE")):
argv0 = sys.argv[0]
pos = argv0.rfind('%s%s%s' % (os.sep, WORKSPACE_DIR, os.sep))
if pos > -1:
dirpath = argv0[0:pos]
if not os.path.isdir(dirpath):
print("ERROR: Cannot access runfiles directory (%s)" %
dirpath)
sys.exit(1)
runfiles = runfiles_lib.CreateDirectoryBased(dirpath)
if not runfiles:
print("ERROR: Cannot load runfiles")
sys.exit(1)
rulesets = []
load_sym_extractor = load_extractor.LoadExtractor()
for bzl_file in bzl_files:
load_symbols = []
try:
load_symbols = load_sym_extractor.extract(bzl_file)
except load_extractor.LoadExtractorError as e:
print("ERROR: Error extracting loaded symbols from %s: %s" %
(bzl_file, str(e)))
sys.exit(2)
# TODO(dzc): Make MacroDocExtractor and RuleDocExtractor stateless.
macro_doc_extractor = macro_extractor.MacroDocExtractor()
rule_doc_extractor = rule_extractor.RuleDocExtractor()
macro_doc_extractor.parse_bzl(bzl_file)
rule_doc_extractor.parse_bzl(bzl_file, load_symbols)
merged_language = merge_languages(macro_doc_extractor.proto(),
rule_doc_extractor.proto())
rulesets.append(
rule.RuleSet(bzl_file, merged_language, macro_doc_extractor.title,
macro_doc_extractor.description, strip_prefix,
options.format))
writer_options = WriterOptions(options.output_dir, options.output_file,
options.zip, options.overview,
options.overview_filename, options.link_ext,
options.site_root)
if options.format == "markdown":
markdown_writer = MarkdownWriter(writer_options, runfiles)
markdown_writer.write(rulesets)
elif options.format == "html":
html_writer = HtmlWriter(writer_options, runfiles)
html_writer.write(rulesets)
else:
sys.stderr.write(
'Invalid output format: %s. Possible values are markdown and html'
% options.format)
