Merge pull request #9012 from pradyunsg/switch-to-furo

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 {

docs/html/_static/important-admonition.css

-.admonition.important {
-  background-color: rgb(219, 250, 244);
-  border: 1px solid rgb(26, 188, 156);
-}
-
-.admonition.important>.admonition-title {
-  color: rgb(26, 188, 156);
-}

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.
@@ -127,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 = []
 
@@ -146,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
 # "<project> v<release> 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
@@ -181,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.
@@ -204,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.
@@ -321,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+ux/pip.pypa.io@pypa.io>'
 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?',

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

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``
 

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/

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

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 <https://github.com/python/peps>`__)
-      - already tracked by another issue
+    - PEP updates (with a corresponding issue in
+      `python/peps <https://github.com/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``.

docs/html/reference/pip.rst

@@ -2,7 +2,6 @@
 pip
 ===
 
-.. contents::
 
 Usage
 *****

docs/html/reference/pip_cache.rst

@@ -4,7 +4,6 @@
 pip cache
 ---------
 
-.. contents::
 
 Usage
 *****

docs/html/reference/pip_check.rst

@@ -4,8 +4,6 @@
 pip check
 =========
 
-.. contents::
-
 
 Usage
 =====

docs/html/reference/pip_config.rst

@@ -5,8 +5,6 @@
 pip config
 ==========
 
-.. contents::
-
 
 Usage
 =====

docs/html/reference/pip_debug.rst

@@ -4,8 +4,6 @@
 pip debug
 =========
 
-.. contents::
-
 
 Usage
 =====

docs/html/reference/pip_download.rst

@@ -5,8 +5,6 @@
 pip download
 ============
 
-.. contents::
-
 
 Usage
 =====

docs/html/reference/pip_freeze.rst

@@ -5,8 +5,6 @@
 pip freeze
 ==========
 
-.. contents::
-
 
 Usage
 =====

docs/html/reference/pip_hash.rst

@@ -4,8 +4,6 @@
 pip hash
 ========
 
-.. contents::
-
 
 Usage
 =====

docs/html/reference/pip_install.rst

@@ -4,7 +4,6 @@
 pip install
 ===========
 
-.. contents::
 
 
 Usage

docs/html/reference/pip_list.rst

@@ -4,7 +4,6 @@
 pip list
 ========
 
-.. contents::
 
 
 Usage

docs/html/reference/pip_search.rst

@@ -4,7 +4,6 @@
 pip search
 ==========
 
-.. contents::
 
 
 Usage

docs/html/reference/pip_show.rst

@@ -4,7 +4,6 @@
 pip show
 ========
 
-.. contents::
 
 
 Usage

docs/html/reference/pip_uninstall.rst

@@ -4,7 +4,6 @@
 pip uninstall
 =============
 
-.. contents::
 
 
 Usage

docs/html/reference/pip_wheel.rst

@@ -5,7 +5,6 @@
 pip wheel
 =========
 
-.. contents::
 
 
 Usage

docs/html/user_guide.rst

@@ -2,8 +2,6 @@
 User Guide
 ==========
 
-.. contents::
-
 
 Running pip
 ===========

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,

tools/requirements/docs.txt

 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