def preview_main(gen_script, default_port):
"""Main entrypoint for previewing documentation.
Args:
gen_script: Generation script, required to generate docs.
default_port: Default port for local HTTP server.
"""
assert isfile(_SPHINX_BUILD), "Please execute via 'bazel run'"
parser = argparse.ArgumentParser()
parser.register('type', 'bool', _str2bool)
parser.add_argument(
"--browser", type='bool', default=True, metavar='BOOL',
help="Open browser. Disable this if you are frequently recompiling.")
parser.add_argument(
"--port", type=int, default=default_port, metavar='PORT',
help="Port for serving doc pages with a HTTP server.")
args = parser.parse_args()
# Choose an arbitrary location for generating documentation.
out_dir = abspath("sphinx-tmp")
if isdir(out_dir):
rmtree(out_dir)
# Generate.
check_call([sys.executable, gen_script, "--out_dir", out_dir])
print("Sphinx preview docs are available at:")
file_url = "file://{}".format(join(out_dir, "index.html"))
browser_url = file_url
print()
print(" {}".format(file_url))
# Serve the current directory for local browsing. Required for MacOS.
# N.B. We serve the preview via a HTTP server because it is necessary for
# certain browsers (Safari on MacOS, possibly Chrome) due to local file
# restrictions.
os.chdir(out_dir)
sockaddr = ("127.0.0.1", args.port)
TCPServer.allow_reuse_address = True
httpd = TCPServer(sockaddr, _Handler)
http_url = "http://{}:{}/index.html".format(*sockaddr)
print()
print(" {}".format(http_url))
# Default to using HTTP serving only on MacOS; on Ubuntu, it can spit
# out errors and exceptions about broken pipes, 404 files, etc.
if sys.platform == "darwin":
browser_url = http_url
# Try the default browser.
if args.browser:
webbrowser.open(browser_url)
# Wait for server.
print()
print("Serving and waiting ... use Ctrl-C to exit.")
httpd.serve_forever()
def serve_forever(self):
"""
Handle requests until an explicit shutdown() request.
Poll for shutdown every poll_interval seconds. Ignores self.timeout.
"""
TCPServer.serve_forever(self, poll_interval=self.poll_interval)
def log_request(*_):
pass
# Serve the current directory for local browsing.
sockaddr = ("127.0.0.1", args.port)
TCPServer.allow_reuse_address = True
httpd = TCPServer(sockaddr, Handler)
http_url = "http://%s:%s/index.html" % sockaddr
# Users can click these as a backup, if the auto-open below doesn't work.
print("Sphinx preview docs are available at:", file=sys.stderr)
print("", file=sys.stderr)
print(" " + http_url, file=sys.stderr)
print("", file=sys.stderr)
print(" " + file_url, file=sys.stderr)
print("", file=sys.stderr)
# Try the default browser, then wait.
if args.browser:
print("Opening webbrowser", file=sys.stderr)
if sys.platform == "darwin":
# macOS
webbrowser.open(http_url)
else:
# Ubuntu
webbrowser.open("./index.html")
print("Serving and waiting ... use Ctrl-C to exit.", file=sys.stderr)
httpd.serve_forever()
def log_request(*_):
pass
# Serve the current directory for local browsing.
sockaddr = ("127.0.0.1", args.port)
TCPServer.allow_reuse_address = True
httpd = TCPServer(sockaddr, Handler)
http_url = "http://%s:%s/index.html" % sockaddr
# Users can click these as a backup, if the auto-open below doesn't work.
print("Sphinx preview docs are available at:", file=sys.stderr)
print("", file=sys.stderr)
print(" " + http_url, file=sys.stderr)
print("", file=sys.stderr)
print(" " + file_url, file=sys.stderr)
print("", file=sys.stderr)
# Try the default browser, then wait.
if args.browser:
print("Opening webbrowser", file=sys.stderr)
if sys.platform == "darwin":
# macOS
webbrowser.open(http_url)
else:
# Ubuntu
webbrowser.open("./index.html")
print("Serving and waiting ... use Ctrl-C to exit.", file=sys.stderr)
httpd.serve_forever()
def serve_forever(self):
"""
Handle requests until an explicit shutdown() request.
Poll for shutdown every poll_interval seconds. Ignores self.timeout.
"""
TCPServer.serve_forever(self, poll_interval=self.poll_interval)
def serve():
httpd = TCPServer((_host, _port), MockHTTPHandler)
httpd.serve_forever()
