Chromium Code Reviews Chromium Code Reviews
Issue 868843002:
net docs: Barebones doc renderer and net_docs target. (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@master| OLD | NEW |
|---|---|
| (Empty) | |
| 1 #!/usr/bin/env python | |
| 2 | |
| 3 # Copyright 2014 The Chromium Authors. All rights reserved. | |
| 4 # Use of this source code is governed by a BSD-style license that can be | |
| 5 # found in the LICENSE file. | |
| 6 | |
| 7 | |
| 8 """Reads, parses, and (optionally) writes as HTML the contents of Markdown | |
| 9 files passed as arguments. Intended for rendering network stack documentation | |
| 10 stored as Markdown in the source tree to a human-readable format.""" | |
| 11 | |
| 12 | |
| 13 import argparse | |
| 14 import os.path | |
| 15 import sys | |
| 16 | |
| 17 | |
| 18 def nth_parent_directory(path, n): | |
| 19 for i in range(n): | |
| 20 path = os.path.dirname(path) | |
| 21 return path | |
| 22 | |
| 23 | |
| 24 # Go up the directory tree from this script and add src/third_party to sys.path | |
| 25 # so "import markdown" can find it in src/third_party/markdown. | |
| 26 SCRIPT_PATH = os.path.abspath(__file__) | |
| 27 SRC_PATH = nth_parent_directory(SCRIPT_PATH, 4) | |
| 28 THIRD_PARTY_PATH = os.path.join(SRC_PATH, 'third_party') | |
| 29 sys.path.insert(0, THIRD_PARTY_PATH) | |
| 30 import markdown | |
| 31 | |
| 32 | |
| 33 def ReadFile(filename): | |
| 34 with open(filename, 'r') as file: | |
| 35 return file.read() | |
| 36 | |
| 37 | |
| 38 def WriteFile(filename, contents): | |
| 39 dir = os.path.dirname(filename) | |
| 40 if not os.path.isdir(dir): | |
| 41 os.mkdir(dir) | |
| 42 with open(filename, 'w') as file: | |
| 43 file.write(contents) | |
| 44 | |
| 45 | |
| 46 TEMPLATE = """ | |
| 47 <html> | |
| 48 <head> | |
| 49 <title>{title}</title> | |
| 50 </head> | |
| 51 <body> | |
| 52 {body} | |
| 53 </body> | |
| 54 </html>""" | |
| 55 | |
| 56 | |
| 57 def FormatPage(markdown_html, title): | |
| 58 # TODO(ttuttle): Add navigation? | |
|
Randy Smith (Not in Mondays)
2015/02/16 14:17:37
I'm probably being clueless, but I'm not sure what
Deprecated (see juliatuttle)
2015/02/20 21:03:55
I meant like a directory tree of available documen
Randy Smith (Not in Mondays)
2015/02/23 14:42:26
No, sounds like a reasonable idea, and the todo is
Deprecated (see juliatuttle)
2015/02/24 14:56:22
Done.
| |
| 59 return TEMPLATE.format(title=title, body=markdown_html) | |
| 60 | |
| 61 | |
| 62 | |
|
Randy Smith (Not in Mondays)
2015/02/16 14:17:36
nit, suggestion: I don't think an extra blank line
Deprecated (see juliatuttle)
2015/02/20 21:03:55
Oh, whoops, that's a typo.
| |
| 63 def ProcessDocs(input_filenames, input_pathname, output_pathname): | |
| 64 """Processes a list of Markdown documentation files. | |
| 65 | |
| 66 If input_pathname and output_pathname are specified, outputs HTML files | |
| 67 into the corresponding subdirectories of output_pathname. If one or both is | |
| 68 not specified, simply ensures the files exist and contain valid Markdown. | |
|
Randy Smith (Not in Mondays)
2015/02/16 14:17:37
Why is input_pathname required to produce output?
Deprecated (see juliatuttle)
2015/02/20 21:03:55
It needs the input pathname so it can figure out w
Randy Smith (Not in Mondays)
2015/02/23 14:42:25
Ah, that makes sense. Add a line indicating that
Deprecated (see juliatuttle)
2015/02/24 14:56:22
Done.
| |
| 69 | |
| 70 Args: | |
| 71 input_filenames: A list of filenames (absolute, or relative to $PWD) of | |
| 72 Markdown files to parse and possibly render. | |
| 73 input_pathname: The base directory from which relative paths to input | |
| 74 filenames are formed. | |
| 75 output_pathname: The output directory into which rendered Markdown files | |
| 76 go, using that relative path. | |
| 77 | |
| 78 Returns: | |
| 79 nothing | |
| 80 | |
| 81 Raises: | |
| 82 IOError: if any of the file operations fail (e.g. input_filenames | |
| 83 contains a non-existent file). | |
| 84 """ | |
| 85 | |
| 86 outputting = (input_pathname is not None) and (output_pathname is not None) | |
| 87 | |
| 88 markdown_parser = markdown.Markdown() | |
| 89 | |
| 90 for input_filename in input_filenames: | |
| 91 markdown_text = ReadFile(input_filename) | |
| 92 markdown_html = markdown_parser.reset().convert(markdown_text) | |
| 93 if not outputting: | |
| 94 continue | |
| 95 | |
| 96 # TODO(ttuttle): Sanitize HTML? | |
|
Randy Smith (Not in Mondays)
2015/02/16 14:17:37
If possible, I'd like to resolve this TODO before
Deprecated (see juliatuttle)
2015/02/20 21:03:55
Yeah, fair, I guess I won't.
| |
| 97 full_html = FormatPage(markdown_html, title=input_filename) | |
| 98 rel_filename = os.path.relpath(input_filename, start=input_pathname) | |
| 99 output_filename = os.path.join(output_pathname, rel_filename) + '.html' | |
| 100 WriteFile(output_filename, full_html) | |
| 101 | |
| 102 | |
| 103 def main(): | |
| 104 parser = argparse.ArgumentParser( | |
| 105 description='Parse and render Markdown documentation') | |
| 106 parser.add_argument('--input_path', default=None, | |
| 107 help="Input path for Markdown; required only if output_path set") | |
| 108 parser.add_argument('--output_path', default=None, | |
| 109 help="Output path for rendered HTML; if unspecified, won't output") | |
| 110 parser.add_argument('filenames', nargs=argparse.REMAINDER) | |
| 111 args = parser.parse_args() | |
| 112 | |
| 113 ProcessDocs(args.filenames, args.input_path, args.output_path) | |
| 114 | |
| 115 return 0 | |
| 116 | |
| 117 | |
| 118 if __name__ == '__main__': | |
| 119 sys.exit(main()) | |
| OLD | NEW |
