diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/html/conf.py | 5 | ||||
-rw-r--r-- | docs/pip_sphinxext.py | 38 |
2 files changed, 27 insertions, 16 deletions
diff --git a/docs/html/conf.py b/docs/html/conf.py index 14ea84bfb..2a4387a35 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -5,6 +5,7 @@ import os import pathlib import re import sys +from typing import List, Tuple # Add the docs/ directory to sys.path, because pip_sphinxext.py is there. docs_dir = os.path.dirname(os.path.dirname(__file__)) @@ -93,10 +94,10 @@ html_use_index = False # List of manual pages generated -def determine_man_pages(): +def determine_man_pages() -> List[Tuple[str, str, str, str, int]]: """Determine which man pages need to be generated.""" - def to_document_name(path, base_dir): + def to_document_name(path: str, base_dir: str) -> str: """Convert a provided path to a Sphinx "document name".""" relative_path = os.path.relpath(path, base_dir) root, _ = os.path.splitext(relative_path) diff --git a/docs/pip_sphinxext.py b/docs/pip_sphinxext.py index 8e5cc7a2c..b6321686f 100644 --- a/docs/pip_sphinxext.py +++ b/docs/pip_sphinxext.py @@ -4,10 +4,12 @@ import optparse import re import sys from textwrap import dedent +from typing import Iterable, List, Optional from docutils import nodes from docutils.parsers import rst from docutils.statemachine import StringList, ViewList +from sphinx.application import Sphinx from pip._internal.cli import cmdoptions from pip._internal.commands import commands_dict, create_command @@ -18,7 +20,7 @@ class PipCommandUsage(rst.Directive): required_arguments = 1 optional_arguments = 3 - def run(self): + def run(self) -> List[nodes.Node]: cmd = create_command(self.arguments[0]) cmd_prefix = "python -m pip" if len(self.arguments) > 1: @@ -33,11 +35,12 @@ class PipCommandUsage(rst.Directive): class PipCommandDescription(rst.Directive): required_arguments = 1 - def run(self): + def run(self) -> List[nodes.Node]: node = nodes.paragraph() node.document = self.state.document desc = ViewList() cmd = create_command(self.arguments[0]) + assert cmd.__doc__ is not None description = dedent(cmd.__doc__) for line in description.split("\n"): desc.append(line, "") @@ -46,7 +49,9 @@ class PipCommandDescription(rst.Directive): class PipOptions(rst.Directive): - def _format_option(self, option, cmd_name=None): + def _format_option( + self, option: optparse.Option, cmd_name: Optional[str] = None + ) -> List[str]: bookmark_line = ( f".. _`{cmd_name}_{option._long_opts[0]}`:" if cmd_name @@ -60,22 +65,27 @@ class PipOptions(rst.Directive): elif option._long_opts: line += option._long_opts[0] if option.takes_value(): - metavar = option.metavar or option.dest.lower() + metavar = option.metavar or option.dest + assert metavar is not None line += f" <{metavar.lower()}>" # fix defaults - opt_help = option.help.replace("%default", str(option.default)) + assert option.help is not None + # https://github.com/python/typeshed/pull/5080 + opt_help = option.help.replace("%default", str(option.default)) # type: ignore # fix paths with sys.prefix opt_help = opt_help.replace(sys.prefix, "<sys.prefix>") return [bookmark_line, "", line, "", " " + opt_help, ""] - def _format_options(self, options, cmd_name=None): + def _format_options( + self, options: Iterable[optparse.Option], cmd_name: Optional[str] = None + ) -> None: for option in options: if option.help == optparse.SUPPRESS_HELP: continue for line in self._format_option(option, cmd_name): self.view_list.append(line, "") - def run(self): + def run(self) -> List[nodes.Node]: node = nodes.paragraph() node.document = self.state.document self.view_list = ViewList() @@ -85,14 +95,14 @@ class PipOptions(rst.Directive): class PipGeneralOptions(PipOptions): - def process_options(self): + def process_options(self) -> None: self._format_options([o() for o in cmdoptions.general_group["options"]]) class PipIndexOptions(PipOptions): required_arguments = 1 - def process_options(self): + def process_options(self) -> None: cmd_name = self.arguments[0] self._format_options( [o() for o in cmdoptions.index_group["options"]], @@ -103,7 +113,7 @@ class PipIndexOptions(PipOptions): class PipCommandOptions(PipOptions): required_arguments = 1 - def process_options(self): + def process_options(self) -> None: cmd = create_command(self.arguments[0]) self._format_options( cmd.parser.option_groups[0].option_list, @@ -112,7 +122,7 @@ class PipCommandOptions(PipOptions): class PipReqFileOptionsReference(PipOptions): - def determine_opt_prefix(self, opt_name): + def determine_opt_prefix(self, opt_name: str) -> str: for command in commands_dict: cmd = create_command(command) if cmd.cmd_opts.has_option(opt_name): @@ -120,7 +130,7 @@ class PipReqFileOptionsReference(PipOptions): raise KeyError(f"Could not identify prefix of opt {opt_name}") - def process_options(self): + def process_options(self) -> None: for option in SUPPORTED_OPTIONS: if getattr(option, "deprecated", False): continue @@ -157,7 +167,7 @@ class PipCLIDirective(rst.Directive): has_content = True optional_arguments = 1 - def run(self): + def run(self) -> List[nodes.Node]: node = nodes.paragraph() node.document = self.state.document @@ -226,7 +236,7 @@ class PipCLIDirective(rst.Directive): return [node] -def setup(app): +def setup(app: Sphinx) -> None: app.add_directive("pip-command-usage", PipCommandUsage) app.add_directive("pip-command-description", PipCommandDescription) app.add_directive("pip-command-options", PipCommandOptions) |