From 5bfc0259f9a4c3d5748f7ca514f3b9c60e34246e Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Mon, 19 Oct 2020 19:47:22 +0530 Subject: [PATCH 1/5] Clarify which version of pip we're seeing --- docs/html/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/html/conf.py b/docs/html/conf.py index adee6fd3c..68951b2c4 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -94,7 +94,8 @@ with open(pip_init) as f: # We have this here because readthedocs plays tricks sometimes and there seems # to be a heisenbug, related to the version of pip discovered. This is here to # help debug that if someone decides to do that in the future. -print(version) +print("pip version:", version) +print("pip release:", release) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. From 19717d170163c8f564d0945beb30776a114e31b9 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Mon, 19 Oct 2020 20:06:04 +0530 Subject: [PATCH 2/5] Switch documentation theme to Furo --- docs/html/conf.py | 25 ++++++------------------- tools/requirements/docs.txt | 3 +-- 2 files changed, 7 insertions(+), 21 deletions(-) diff --git a/docs/html/conf.py b/docs/html/conf.py index 68951b2c4..7983187e9 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -128,9 +128,6 @@ exclude_patterns = ['build/'] # output. They are ignored by default. # show_authors = False -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] @@ -147,25 +144,18 @@ sphinx_tabs_nowarn = True # The theme to use for HTML and HTML Help pages. Major themes that come with # Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = "pypa_theme" +html_theme = "furo" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -html_theme_options = { - 'collapsiblesidebar': True, - 'externalrefs': True, - 'navigation_depth': 3, - 'issues_url': 'https://github.com/pypa/pip/issues', - 'codebgcolor': '#eeffcc', - 'codetextcolor': '#333333', -} +html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -# html_title = None +html_title = f"{project} documentation v{release}" # A shorter title for the navigation bar. Default is the same as html_title. # html_short_title = None @@ -182,7 +172,7 @@ html_theme_options = { # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -205,10 +195,7 @@ smartquotes = True smartquotes_action = "qe" # Custom sidebar templates, maps document names to template names. -html_sidebars = { - '**': ['localtoc.html', 'relations.html'], - 'index': ['localtoc.html'] -} +html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. @@ -322,7 +309,7 @@ docs_feedback_admonition_type = 'important' docs_feedback_big_doc_lines = 50 # bigger docs will have a banner on top docs_feedback_email = 'Docs UX Team ' docs_feedback_excluded_documents = { # these won't have any banners - 'news', + 'news', 'reference/index', } docs_feedback_questions_list = ( 'What problem were you trying to solve when you came to this page?', diff --git a/tools/requirements/docs.txt b/tools/requirements/docs.txt index 77a940c08..0c5103d0a 100644 --- a/tools/requirements/docs.txt +++ b/tools/requirements/docs.txt @@ -1,6 +1,5 @@ sphinx == 3.2.1 -git+https://github.com/python/python-docs-theme.git#egg=python-docs-theme -git+https://github.com/pypa/pypa-docs-theme.git#egg=pypa-docs-theme +furo sphinx-inline-tabs # `docs.pipext` uses pip's internals to generate documentation. So, we install From f3ee03d6d0a8551bc65d4a0436dc31b23472085d Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Mon, 19 Oct 2020 20:06:17 +0530 Subject: [PATCH 3/5] Drop custom styling for admonitions --- docs/docs_feedback_sphinxext.py | 1 - docs/html/_static/important-admonition.css | 8 -------- 2 files changed, 9 deletions(-) delete mode 100644 docs/html/_static/important-admonition.css diff --git a/docs/docs_feedback_sphinxext.py b/docs/docs_feedback_sphinxext.py index 90f2ddd74..86eb3d61a 100644 --- a/docs/docs_feedback_sphinxext.py +++ b/docs/docs_feedback_sphinxext.py @@ -155,7 +155,6 @@ def setup(app: Sphinx) -> Dict[str, Union[bool, str]]: rebuild=rebuild_trigger, ) - app.add_css_file('important-admonition.css') app.connect('source-read', _modify_rst_document_source_on_read) return { diff --git a/docs/html/_static/important-admonition.css b/docs/html/_static/important-admonition.css deleted file mode 100644 index a73ae2e4d..000000000 --- a/docs/html/_static/important-admonition.css +++ /dev/null @@ -1,8 +0,0 @@ -.admonition.important { - background-color: rgb(219, 250, 244); - border: 1px solid rgb(26, 188, 156); -} - -.admonition.important>.admonition-title { - color: rgb(26, 188, 156); -} From 6962284236bc6e2ffc3256f5f70876b70d4d353b Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Mon, 19 Oct 2020 20:07:12 +0530 Subject: [PATCH 4/5] Remove inline table of contents Furo provides a fully-fleshed-out right sidebar that provides an in-page table of contents, that's scrollable and does not interrupt content. --- docs/html/development/architecture/overview.rst | 1 - docs/html/reference/pip.rst | 1 - docs/html/reference/pip_cache.rst | 1 - docs/html/reference/pip_check.rst | 2 -- docs/html/reference/pip_config.rst | 2 -- docs/html/reference/pip_debug.rst | 2 -- docs/html/reference/pip_download.rst | 2 -- docs/html/reference/pip_freeze.rst | 2 -- docs/html/reference/pip_hash.rst | 2 -- docs/html/reference/pip_install.rst | 1 - docs/html/reference/pip_list.rst | 1 - docs/html/reference/pip_search.rst | 1 - docs/html/reference/pip_show.rst | 1 - docs/html/reference/pip_uninstall.rst | 1 - docs/html/reference/pip_wheel.rst | 1 - docs/html/user_guide.rst | 2 -- 16 files changed, 23 deletions(-) diff --git a/docs/html/development/architecture/overview.rst b/docs/html/development/architecture/overview.rst index 637a22f2f..f9bcfb873 100644 --- a/docs/html/development/architecture/overview.rst +++ b/docs/html/development/architecture/overview.rst @@ -4,7 +4,6 @@ developers welcome your help to complete this documentation. If you're interested in helping out, please let us know in the `tracking issue`_. -.. contents:: **************************** Broad functionality overview diff --git a/docs/html/reference/pip.rst b/docs/html/reference/pip.rst index 298a1101d..1f52630f6 100644 --- a/docs/html/reference/pip.rst +++ b/docs/html/reference/pip.rst @@ -2,7 +2,6 @@ pip === -.. contents:: Usage ***** diff --git a/docs/html/reference/pip_cache.rst b/docs/html/reference/pip_cache.rst index c443a6f3a..0a23c510d 100644 --- a/docs/html/reference/pip_cache.rst +++ b/docs/html/reference/pip_cache.rst @@ -4,7 +4,6 @@ pip cache --------- -.. contents:: Usage ***** diff --git a/docs/html/reference/pip_check.rst b/docs/html/reference/pip_check.rst index 3b2ecb511..268cf9a14 100644 --- a/docs/html/reference/pip_check.rst +++ b/docs/html/reference/pip_check.rst @@ -4,8 +4,6 @@ pip check ========= -.. contents:: - Usage ===== diff --git a/docs/html/reference/pip_config.rst b/docs/html/reference/pip_config.rst index 14b1ac775..8b2f84630 100644 --- a/docs/html/reference/pip_config.rst +++ b/docs/html/reference/pip_config.rst @@ -5,8 +5,6 @@ pip config ========== -.. contents:: - Usage ===== diff --git a/docs/html/reference/pip_debug.rst b/docs/html/reference/pip_debug.rst index a077a169b..4023533c9 100644 --- a/docs/html/reference/pip_debug.rst +++ b/docs/html/reference/pip_debug.rst @@ -4,8 +4,6 @@ pip debug ========= -.. contents:: - Usage ===== diff --git a/docs/html/reference/pip_download.rst b/docs/html/reference/pip_download.rst index b600d15e5..4f15314d7 100644 --- a/docs/html/reference/pip_download.rst +++ b/docs/html/reference/pip_download.rst @@ -5,8 +5,6 @@ pip download ============ -.. contents:: - Usage ===== diff --git a/docs/html/reference/pip_freeze.rst b/docs/html/reference/pip_freeze.rst index 152823a08..352f7d321 100644 --- a/docs/html/reference/pip_freeze.rst +++ b/docs/html/reference/pip_freeze.rst @@ -5,8 +5,6 @@ pip freeze ========== -.. contents:: - Usage ===== diff --git a/docs/html/reference/pip_hash.rst b/docs/html/reference/pip_hash.rst index e9f5964dd..7df0d5a4f 100644 --- a/docs/html/reference/pip_hash.rst +++ b/docs/html/reference/pip_hash.rst @@ -4,8 +4,6 @@ pip hash ======== -.. contents:: - Usage ===== diff --git a/docs/html/reference/pip_install.rst b/docs/html/reference/pip_install.rst index be974dacf..1a5507fdc 100644 --- a/docs/html/reference/pip_install.rst +++ b/docs/html/reference/pip_install.rst @@ -4,7 +4,6 @@ pip install =========== -.. contents:: Usage diff --git a/docs/html/reference/pip_list.rst b/docs/html/reference/pip_list.rst index bda322a86..5119a804c 100644 --- a/docs/html/reference/pip_list.rst +++ b/docs/html/reference/pip_list.rst @@ -4,7 +4,6 @@ pip list ======== -.. contents:: Usage diff --git a/docs/html/reference/pip_search.rst b/docs/html/reference/pip_search.rst index 2d1a2aa69..9905a1baf 100644 --- a/docs/html/reference/pip_search.rst +++ b/docs/html/reference/pip_search.rst @@ -4,7 +4,6 @@ pip search ========== -.. contents:: Usage diff --git a/docs/html/reference/pip_show.rst b/docs/html/reference/pip_show.rst index bcbe4e820..b603f786f 100644 --- a/docs/html/reference/pip_show.rst +++ b/docs/html/reference/pip_show.rst @@ -4,7 +4,6 @@ pip show ======== -.. contents:: Usage diff --git a/docs/html/reference/pip_uninstall.rst b/docs/html/reference/pip_uninstall.rst index fbbeddd45..f1c69d09c 100644 --- a/docs/html/reference/pip_uninstall.rst +++ b/docs/html/reference/pip_uninstall.rst @@ -4,7 +4,6 @@ pip uninstall ============= -.. contents:: Usage diff --git a/docs/html/reference/pip_wheel.rst b/docs/html/reference/pip_wheel.rst index f6430bfed..c2a9543fc 100644 --- a/docs/html/reference/pip_wheel.rst +++ b/docs/html/reference/pip_wheel.rst @@ -5,7 +5,6 @@ pip wheel ========= -.. contents:: Usage diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 677a8a063..55e0c9268 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -2,8 +2,6 @@ User Guide ========== -.. contents:: - Running pip =========== From 321163fb98e2733195a8e44c86e9466b989f5008 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Thu, 12 Nov 2020 07:29:03 +0530 Subject: [PATCH 5/5] Fix misplaced blockquotes Signed-off-by: Pradyun Gedam --- .../architecture/upgrade-options.rst | 24 +++++++-------- docs/html/development/ci.rst | 30 +++++++++---------- docs/html/development/getting-started.rst | 6 ++-- docs/html/development/issue-triage.rst | 26 ++++++++-------- docs/pip_sphinxext.py | 2 +- 5 files changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/html/development/architecture/upgrade-options.rst b/docs/html/development/architecture/upgrade-options.rst index 0527101f8..6196413ef 100644 --- a/docs/html/development/architecture/upgrade-options.rst +++ b/docs/html/development/architecture/upgrade-options.rst @@ -34,18 +34,18 @@ relevant if ``--upgrade`` is specified. The base behaviour is to allow packages specified on pip's command line to be upgraded. This option controls what *other* packages can be upgraded: - * ``eager`` - all packages will be upgraded to the latest possible version. - It should be noted here that pip's current resolution algorithm isn't even - aware of packages other than those specified on the command line, and - those identified as dependencies. This may or may not be true of the new - resolver. - * ``only-if-needed`` - packages are only upgraded if they are named in the - pip command or a requirement file (i.e, they are direct requirements), or - an upgraded parent needs a later version of the dependency than is - currently installed. - * ``to-satisfy-only`` (**undocumented**) - packages are not upgraded (not - even direct requirements) unless the currently installed version fails to - satisfy a requirement (either explicitly specified or a dependency). +* ``eager`` - all packages will be upgraded to the latest possible version. + It should be noted here that pip's current resolution algorithm isn't even + aware of packages other than those specified on the command line, and + those identified as dependencies. This may or may not be true of the new + resolver. +* ``only-if-needed`` - packages are only upgraded if they are named in the + pip command or a requirement file (i.e, they are direct requirements), or + an upgraded parent needs a later version of the dependency than is + currently installed. +* ``to-satisfy-only`` (**undocumented**) - packages are not upgraded (not + even direct requirements) unless the currently installed version fails to + satisfy a requirement (either explicitly specified or a dependency). ``--force-reinstall`` diff --git a/docs/html/development/ci.rst b/docs/html/development/ci.rst index 7f214a3b8..5befb316a 100644 --- a/docs/html/development/ci.rst +++ b/docs/html/development/ci.rst @@ -17,24 +17,24 @@ Supported interpreters pip support a variety of Python interpreters: - - CPython 2.7 - - CPython 3.5 - - CPython 3.6 - - CPython 3.7 - - CPython 3.8 - - Latest PyPy - - Latest PyPy3 +- CPython 2.7 +- CPython 3.5 +- CPython 3.6 +- CPython 3.7 +- CPython 3.8 +- Latest PyPy +- Latest PyPy3 on different operating systems: - - Linux - - Windows - - MacOS +- Linux +- Windows +- MacOS and on different architectures: - - x64 - - x86 +- x64 +- x86 so 42 hypothetical interpreters. @@ -66,9 +66,9 @@ Services pip test suite and checks are distributed on three different platforms that provides free executors for open source packages: - - `GitHub Actions`_ (Used for code quality and development tasks) - - `Azure DevOps CI`_ (Used for tests) - - `Travis CI`_ (Used for PyPy tests) +- `GitHub Actions`_ (Used for code quality and development tasks) +- `Azure DevOps CI`_ (Used for tests) +- `Travis CI`_ (Used for PyPy tests) .. _`Travis CI`: https://travis-ci.org/ .. _`Azure DevOps CI`: https://azure.microsoft.com/en-us/services/devops/ diff --git a/docs/html/development/getting-started.rst b/docs/html/development/getting-started.rst index 436ed241b..94ff37fc3 100644 --- a/docs/html/development/getting-started.rst +++ b/docs/html/development/getting-started.rst @@ -157,9 +157,9 @@ in order to start contributing. * A guide on `triaging issues`_ for issue tracker * Getting started with Git - - `Hello World for Git`_ - - `Understanding the GitHub flow`_ - - `Start using Git on the command line`_ + - `Hello World for Git`_ + - `Understanding the GitHub flow`_ + - `Start using Git on the command line`_ .. _`open an issue`: https://github.com/pypa/pip/issues/new?title=Trouble+with+pip+development+environment diff --git a/docs/html/development/issue-triage.rst b/docs/html/development/issue-triage.rst index a887bda62..9b5e5cc1c 100644 --- a/docs/html/development/issue-triage.rst +++ b/docs/html/development/issue-triage.rst @@ -276,16 +276,16 @@ An issue may be considered resolved and closed when: - for each possible improvement or problem represented in the issue discussion: - - Consensus has been reached on a specific action and the actions - appear to be external to the project, with no follow up needed - in the project afterwards. + - Consensus has been reached on a specific action and the actions + appear to be external to the project, with no follow up needed + in the project afterwards. - - PEP updates (with a corresponding issue in - `python/peps `__) - - already tracked by another issue + - PEP updates (with a corresponding issue in + `python/peps `__) + - already tracked by another issue - - A project-specific issue has been identified and the issue no - longer occurs as of the latest commit on the master branch. + - A project-specific issue has been identified and the issue no + longer occurs as of the latest commit on the master branch. - An enhancement or feature request no longer has a proponent and the maintainers don't think it's worth keeping open. @@ -305,8 +305,8 @@ Common issues manager-managed pip/python installation (specifically with Debian/Ubuntu). These typically present themselves as: - #. Not being able to find installed packages - #. basic libraries not able to be found, fundamental OS components missing - #. In these situations you will want to make sure that we know how they got - their Python and pip. Knowing the relevant package manager commands can - help, e.g. ``dpkg -S``. + #. Not being able to find installed packages + #. basic libraries not able to be found, fundamental OS components missing + #. In these situations you will want to make sure that we know how they got + their Python and pip. Knowing the relevant package manager commands can + help, e.g. ``dpkg -S``. diff --git a/docs/pip_sphinxext.py b/docs/pip_sphinxext.py index 9386d71e7..2486d5c33 100644 --- a/docs/pip_sphinxext.py +++ b/docs/pip_sphinxext.py @@ -143,7 +143,7 @@ class PipReqFileOptionsReference(PipOptions): prefix = '{}_'.format(self.determine_opt_prefix(opt_name)) self.view_list.append( - ' * :ref:`{short}{long}<{prefix}{opt_name}>`'.format( + '* :ref:`{short}{long}<{prefix}{opt_name}>`'.format( short=short_opt_name, long=opt_name, prefix=prefix,