mirror of https://github.com/pypa/pip
Merge pull request #9672 from jdufresne/mypy-docs
Complete typing of docs directory
This commit is contained in:
commit
bcbfbaa515
|
@ -66,7 +66,7 @@ repos:
|
||||||
rev: v0.800
|
rev: v0.800
|
||||||
hooks:
|
hooks:
|
||||||
- id: mypy
|
- id: mypy
|
||||||
exclude: docs|tests
|
exclude: tests
|
||||||
args: ["--pretty"]
|
args: ["--pretty"]
|
||||||
additional_dependencies: ['nox==2020.12.31']
|
additional_dependencies: ['nox==2020.12.31']
|
||||||
|
|
||||||
|
|
|
@ -5,6 +5,7 @@ import os
|
||||||
import pathlib
|
import pathlib
|
||||||
import re
|
import re
|
||||||
import sys
|
import sys
|
||||||
|
from typing import List, Tuple
|
||||||
|
|
||||||
# Add the docs/ directory to sys.path, because pip_sphinxext.py is there.
|
# Add the docs/ directory to sys.path, because pip_sphinxext.py is there.
|
||||||
docs_dir = os.path.dirname(os.path.dirname(__file__))
|
docs_dir = os.path.dirname(os.path.dirname(__file__))
|
||||||
|
@ -93,10 +94,10 @@ html_use_index = False
|
||||||
|
|
||||||
|
|
||||||
# List of manual pages generated
|
# 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."""
|
"""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"."""
|
"""Convert a provided path to a Sphinx "document name"."""
|
||||||
relative_path = os.path.relpath(path, base_dir)
|
relative_path = os.path.relpath(path, base_dir)
|
||||||
root, _ = os.path.splitext(relative_path)
|
root, _ = os.path.splitext(relative_path)
|
||||||
|
|
|
@ -4,10 +4,12 @@ import optparse
|
||||||
import re
|
import re
|
||||||
import sys
|
import sys
|
||||||
from textwrap import dedent
|
from textwrap import dedent
|
||||||
|
from typing import Iterable, List, Optional
|
||||||
|
|
||||||
from docutils import nodes
|
from docutils import nodes
|
||||||
from docutils.parsers import rst
|
from docutils.parsers import rst
|
||||||
from docutils.statemachine import StringList, ViewList
|
from docutils.statemachine import StringList, ViewList
|
||||||
|
from sphinx.application import Sphinx
|
||||||
|
|
||||||
from pip._internal.cli import cmdoptions
|
from pip._internal.cli import cmdoptions
|
||||||
from pip._internal.commands import commands_dict, create_command
|
from pip._internal.commands import commands_dict, create_command
|
||||||
|
@ -18,7 +20,7 @@ class PipCommandUsage(rst.Directive):
|
||||||
required_arguments = 1
|
required_arguments = 1
|
||||||
optional_arguments = 3
|
optional_arguments = 3
|
||||||
|
|
||||||
def run(self):
|
def run(self) -> List[nodes.Node]:
|
||||||
cmd = create_command(self.arguments[0])
|
cmd = create_command(self.arguments[0])
|
||||||
cmd_prefix = "python -m pip"
|
cmd_prefix = "python -m pip"
|
||||||
if len(self.arguments) > 1:
|
if len(self.arguments) > 1:
|
||||||
|
@ -33,11 +35,12 @@ class PipCommandUsage(rst.Directive):
|
||||||
class PipCommandDescription(rst.Directive):
|
class PipCommandDescription(rst.Directive):
|
||||||
required_arguments = 1
|
required_arguments = 1
|
||||||
|
|
||||||
def run(self):
|
def run(self) -> List[nodes.Node]:
|
||||||
node = nodes.paragraph()
|
node = nodes.paragraph()
|
||||||
node.document = self.state.document
|
node.document = self.state.document
|
||||||
desc = ViewList()
|
desc = ViewList()
|
||||||
cmd = create_command(self.arguments[0])
|
cmd = create_command(self.arguments[0])
|
||||||
|
assert cmd.__doc__ is not None
|
||||||
description = dedent(cmd.__doc__)
|
description = dedent(cmd.__doc__)
|
||||||
for line in description.split("\n"):
|
for line in description.split("\n"):
|
||||||
desc.append(line, "")
|
desc.append(line, "")
|
||||||
|
@ -46,7 +49,9 @@ class PipCommandDescription(rst.Directive):
|
||||||
|
|
||||||
|
|
||||||
class PipOptions(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 = (
|
bookmark_line = (
|
||||||
f".. _`{cmd_name}_{option._long_opts[0]}`:"
|
f".. _`{cmd_name}_{option._long_opts[0]}`:"
|
||||||
if cmd_name
|
if cmd_name
|
||||||
|
@ -60,22 +65,27 @@ class PipOptions(rst.Directive):
|
||||||
elif option._long_opts:
|
elif option._long_opts:
|
||||||
line += option._long_opts[0]
|
line += option._long_opts[0]
|
||||||
if option.takes_value():
|
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()}>"
|
line += f" <{metavar.lower()}>"
|
||||||
# fix defaults
|
# 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
|
# fix paths with sys.prefix
|
||||||
opt_help = opt_help.replace(sys.prefix, "<sys.prefix>")
|
opt_help = opt_help.replace(sys.prefix, "<sys.prefix>")
|
||||||
return [bookmark_line, "", line, "", " " + opt_help, ""]
|
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:
|
for option in options:
|
||||||
if option.help == optparse.SUPPRESS_HELP:
|
if option.help == optparse.SUPPRESS_HELP:
|
||||||
continue
|
continue
|
||||||
for line in self._format_option(option, cmd_name):
|
for line in self._format_option(option, cmd_name):
|
||||||
self.view_list.append(line, "")
|
self.view_list.append(line, "")
|
||||||
|
|
||||||
def run(self):
|
def run(self) -> List[nodes.Node]:
|
||||||
node = nodes.paragraph()
|
node = nodes.paragraph()
|
||||||
node.document = self.state.document
|
node.document = self.state.document
|
||||||
self.view_list = ViewList()
|
self.view_list = ViewList()
|
||||||
|
@ -85,14 +95,14 @@ class PipOptions(rst.Directive):
|
||||||
|
|
||||||
|
|
||||||
class PipGeneralOptions(PipOptions):
|
class PipGeneralOptions(PipOptions):
|
||||||
def process_options(self):
|
def process_options(self) -> None:
|
||||||
self._format_options([o() for o in cmdoptions.general_group["options"]])
|
self._format_options([o() for o in cmdoptions.general_group["options"]])
|
||||||
|
|
||||||
|
|
||||||
class PipIndexOptions(PipOptions):
|
class PipIndexOptions(PipOptions):
|
||||||
required_arguments = 1
|
required_arguments = 1
|
||||||
|
|
||||||
def process_options(self):
|
def process_options(self) -> None:
|
||||||
cmd_name = self.arguments[0]
|
cmd_name = self.arguments[0]
|
||||||
self._format_options(
|
self._format_options(
|
||||||
[o() for o in cmdoptions.index_group["options"]],
|
[o() for o in cmdoptions.index_group["options"]],
|
||||||
|
@ -103,7 +113,7 @@ class PipIndexOptions(PipOptions):
|
||||||
class PipCommandOptions(PipOptions):
|
class PipCommandOptions(PipOptions):
|
||||||
required_arguments = 1
|
required_arguments = 1
|
||||||
|
|
||||||
def process_options(self):
|
def process_options(self) -> None:
|
||||||
cmd = create_command(self.arguments[0])
|
cmd = create_command(self.arguments[0])
|
||||||
self._format_options(
|
self._format_options(
|
||||||
cmd.parser.option_groups[0].option_list,
|
cmd.parser.option_groups[0].option_list,
|
||||||
|
@ -112,7 +122,7 @@ class PipCommandOptions(PipOptions):
|
||||||
|
|
||||||
|
|
||||||
class PipReqFileOptionsReference(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:
|
for command in commands_dict:
|
||||||
cmd = create_command(command)
|
cmd = create_command(command)
|
||||||
if cmd.cmd_opts.has_option(opt_name):
|
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}")
|
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:
|
for option in SUPPORTED_OPTIONS:
|
||||||
if getattr(option, "deprecated", False):
|
if getattr(option, "deprecated", False):
|
||||||
continue
|
continue
|
||||||
|
@ -157,7 +167,7 @@ class PipCLIDirective(rst.Directive):
|
||||||
has_content = True
|
has_content = True
|
||||||
optional_arguments = 1
|
optional_arguments = 1
|
||||||
|
|
||||||
def run(self):
|
def run(self) -> List[nodes.Node]:
|
||||||
node = nodes.paragraph()
|
node = nodes.paragraph()
|
||||||
node.document = self.state.document
|
node.document = self.state.document
|
||||||
|
|
||||||
|
@ -226,7 +236,7 @@ class PipCLIDirective(rst.Directive):
|
||||||
return [node]
|
return [node]
|
||||||
|
|
||||||
|
|
||||||
def setup(app):
|
def setup(app: Sphinx) -> None:
|
||||||
app.add_directive("pip-command-usage", PipCommandUsage)
|
app.add_directive("pip-command-usage", PipCommandUsage)
|
||||||
app.add_directive("pip-command-description", PipCommandDescription)
|
app.add_directive("pip-command-description", PipCommandDescription)
|
||||||
app.add_directive("pip-command-options", PipCommandOptions)
|
app.add_directive("pip-command-options", PipCommandOptions)
|
||||||
|
|
Loading…
Reference in New Issue