diff options
| author | ttuttle <ttuttle@chromium.org> | 2015-02-24 10:07:47 -0800 |
|---|---|---|
| committer | Commit bot <commit-bot@chromium.org> | 2015-02-24 18:08:29 +0000 |
| commit | a898dd47f3cadba45edc5fa57c9772545bf8b8f2 (patch) | |
| tree | 51ce8775ab235c7fc03996b769131781ca6ef232 /net | |
| parent | 97568a816ed5fe0a69a2c0f6d0987381899f58d8 (diff) | |
| download | chromium_src-a898dd47f3cadba45edc5fa57c9772545bf8b8f2.zip chromium_src-a898dd47f3cadba45edc5fa57c9772545bf8b8f2.tar.gz chromium_src-a898dd47f3cadba45edc5fa57c9772545bf8b8f2.tar.bz2 | |
net docs: Barebones doc renderer and net_docs target.
Add a barebones Python script to render network stack documentation
(into $PRODUCT_DIR/net/docs) and a gyp action to call the script.
BUG=451160
Review URL: https://codereview.chromium.org/868843002
Cr-Commit-Position: refs/heads/master@{#317825}
Diffstat (limited to 'net')
| -rw-r--r-- | net/README.md | 1 | ||||
| -rw-r--r-- | net/net.gyp | 28 | ||||
| -rw-r--r-- | net/net.gypi | 6 | ||||
| -rwxr-xr-x | net/tools/net_docs/net_docs.py | 117 |
4 files changed, 152 insertions, 0 deletions
diff --git a/net/README.md b/net/README.md new file mode 100644 index 0000000..0dcb437 --- /dev/null +++ b/net/README.md @@ -0,0 +1 @@ +TODO: Add network stack documentation. :) diff --git a/net/net.gyp b/net/net.gyp index 5c0dbe7..54f90bd 100644 --- a/net/net.gyp +++ b/net/net.gyp @@ -1079,6 +1079,34 @@ ], }, { + 'target_name': 'net_docs', + 'type': 'none', + 'actions': [ + { + 'action_name': 'net_docs', + 'variables': { + 'net_docs_input_dir': '.', + }, + 'inputs': [ + '<@(net_docs_sources)', + ], + 'outputs': [ + '<(net_docs_output_dir)', + ], + 'action': [ + 'python', + '<(net_docs_script)', + '--input_path', + '<(net_docs_input_dir)', + '--output_path', + '<(net_docs_output_dir)', + '<@(net_docs_sources)', + ], + 'message': 'Rendering network stack documentation', + } + ], + }, + { 'target_name': 'http_server', 'type': 'static_library', 'variables': { 'enable_wexit_time_destructors': 1, }, diff --git a/net/net.gypi b/net/net.gypi index dc9d5d8..a40989b 100644 --- a/net/net.gypi +++ b/net/net.gypi @@ -1772,5 +1772,11 @@ 'net_base_test_mac_ios_sources': [ 'base/mac/url_conversions_unittest.mm', ], + 'net_docs_script': 'tools/net_docs/net_docs.py', + 'net_docs_sources': [ + 'README.md', + 'sdch/README.md', + ], + 'net_docs_output_dir': '<(PRODUCT_DIR)/net/docs', } } diff --git a/net/tools/net_docs/net_docs.py b/net/tools/net_docs/net_docs.py new file mode 100755 index 0000000..b803196 --- /dev/null +++ b/net/tools/net_docs/net_docs.py @@ -0,0 +1,117 @@ +#!/usr/bin/env python +# Copyright 2015 The Chromium Authors. All rights reserved. +# Use of this source code is governed by a BSD-style license that can be +# found in the LICENSE file. + + +"""Reads, parses, and (optionally) writes as HTML the contents of Markdown +files passed as arguments. Intended for rendering network stack documentation +stored as Markdown in the source tree to a human-readable format.""" + + +import argparse +import os.path +import sys + + +def nth_parent_directory(path, n): + for i in range(n): + path = os.path.dirname(path) + return path + + +# Go up the directory tree from this script and add src/third_party to sys.path +# so "import markdown" can find it in src/third_party/markdown. +SCRIPT_PATH = os.path.abspath(__file__) +SRC_PATH = nth_parent_directory(SCRIPT_PATH, 4) +THIRD_PARTY_PATH = os.path.join(SRC_PATH, 'third_party') +sys.path.insert(0, THIRD_PARTY_PATH) +import markdown + + +def ReadFile(filename): + with open(filename, 'r') as file: + return file.read() + + +def WriteFile(filename, contents): + dir = os.path.dirname(filename) + if not os.path.isdir(dir): + os.mkdir(dir) + with open(filename, 'w') as file: + file.write(contents) + + +TEMPLATE = """ +<html> + <head> + <title>{title}</title> + </head> + <body> + {body} + </body> +</html>""" + + +def FormatPage(markdown_html, title): + # TODO(ttuttle): Add a navigation list / table of contents of available + # Markdown files, perhaps? + return TEMPLATE.format(title=title, body=markdown_html) + + +def ProcessDocs(input_filenames, input_pathname, output_pathname): + """Processes a list of Markdown documentation files. + + If input_pathname and output_pathname are specified, outputs HTML files + into the corresponding subdirectories of output_pathname. If one or both is + not specified, simply ensures the files exist and contain valid Markdown. + + Args: + input_filenames: A list of filenames (absolute, or relative to $PWD) of + Markdown files to parse and possibly render. + input_pathname: The base directory of the input files. (Needed so they + can be placed in the same relative path in the output path.) + output_pathname: The output directory into which rendered Markdown files + go, using that relative path. + + Returns: + nothing + + Raises: + IOError: if any of the file operations fail (e.g. input_filenames + contains a non-existent file). + """ + + outputting = (input_pathname is not None) and (output_pathname is not None) + + markdown_parser = markdown.Markdown() + + for input_filename in input_filenames: + markdown_text = ReadFile(input_filename) + markdown_html = markdown_parser.reset().convert(markdown_text) + if not outputting: + continue + + full_html = FormatPage(markdown_html, title=input_filename) + rel_filename = os.path.relpath(input_filename, start=input_pathname) + output_filename = os.path.join(output_pathname, rel_filename) + '.html' + WriteFile(output_filename, full_html) + + +def main(): + parser = argparse.ArgumentParser( + description='Parse and render Markdown documentation') + parser.add_argument('--input_path', default=None, + help="Input path for Markdown; required only if output_path set") + parser.add_argument('--output_path', default=None, + help="Output path for rendered HTML; if unspecified, won't output") + parser.add_argument('filenames', nargs=argparse.REMAINDER) + args = parser.parse_args() + + ProcessDocs(args.filenames, args.input_path, args.output_path) + + return 0 + + +if __name__ == '__main__': + sys.exit(main()) |