Source code for waves._docs
"""Internal API module implementing the ``docs`` subcommand behavior.
Should raise ``RuntimeError`` or a derived class of :class:`waves.exceptions.WAVESError` to allow the CLI implementation
to convert stack-trace/exceptions into STDERR message and non-zero exit codes.
"""
import sys
import pathlib
import argparse
_exclude_from_namespace = set(globals().keys())
[docs]
def get_parser() -> argparse.ArgumentParser:
"""Return a 'no-help' parser for the docs subcommand
:return: parser
"""
parser = argparse.ArgumentParser(add_help=False)
parser.add_argument(
"-p",
"--print-local-path",
action="store_true",
help=(
"Print the path to the locally installed documentation index file. "
"As an alternative to the docs sub-command, open index.html in a web browser "
"(default: %(default)s)"
),
)
return parser
[docs]
def main(documentation_index: pathlib.Path, print_local_path: bool = False) -> None:
"""Open the package HTML documentation in the system default web browser or print the path to the documentation
index file.
:param print_local_path: Flag to print the local path to terminal instead of calling the default web browser
"""
if print_local_path:
if documentation_index.exists():
print(documentation_index, file=sys.stdout)
else:
# This should only be reached if the package installation structure doesn't match the assumptions in
# _settings.py. It is used by the Conda build tests as a sign-of-life that the assumptions are correct.
raise RuntimeError("Could not find package documentation HTML index file")
else:
import webbrowser
success = webbrowser.open(str(documentation_index))
if not success:
raise RuntimeError(
"Could not open a web browser. Is your system default browser set? Are you working over SSH? "
"Try running ``waves docs --print-local-path`` and opening the reported path directly."
)
# Limit help() and 'from module import *' behavior to the module's public API
_module_objects = set(globals().keys()) - _exclude_from_namespace
__all__ = [name for name in _module_objects if not name.startswith("_")]