sphinx formatting change and fix CLI docs (#5032)

* sphinx formatting change.

* minor doc formatting improvements.

* check point progress

* Get the CLI docs generating again.

* Add news item for fixed CLI documentation.

* Dont skip build of docs changes.

* fix linting

.github/workflows/ci.yaml

@@ -3,7 +3,6 @@ name: CI
 on:
   push:
     paths-ignore:
-      - "docs/**"
       - "news/**"
       - "examples/**"
       - "peeps/**"
@@ -19,7 +18,6 @@ on:
       - main
   pull_request:
     paths-ignore:
-      - "docs/**"
       - "news/**"
       - "examples/**"
       - "peeps/**"

docs/advanced.rst

@@ -46,14 +46,15 @@ the following command:
 Alternatively the index may be specified by full url, and it will be added to the ``Pipfile`` with a generated name
 unless it already exists in which case the existing name with be reused when pinning the package index.
 
-**Note:** In prior versions of ``pipenv`` you could specify ``--extra-index-urls`` to the ``pip`` resolver and avoid
-specifically matching the expected index by name.   That functionality was deprecated in favor of index restricted
-packages, which is a simplifying assumption that is more security mindful.  The pip documentation has the following
-warning around the ``--extra-index-urls`` option::
+.. note::
+    In prior versions of ``pipenv`` you could specify ``--extra-index-urls`` to the ``pip`` resolver and avoid
+    specifically matching the expected index by name.   That functionality was deprecated in favor of index restricted
+    packages, which is a simplifying assumption that is more security mindful.  The pip documentation has the following
+    warning around the ``--extra-index-urls`` option:
 
-> Using this option to search for packages which are not in the main repository (such as private packages) is unsafe,
-per a security vulnerability called dependency confusion: an attacker can claim the package on the public repository
-in a way that will ensure it gets chosen over the private package.
+    *Using this option to search for packages which are not in the main repository (such as private packages) is unsafe,
+    per a security vulnerability called dependency confusion: an attacker can claim the package on the public repository
+    in a way that will ensure it gets chosen over the private package.*
 
 Should you wish to use an alternative default index other than PyPI: simply do not specify PyPI as one of the
 sources in your ``Pipfile``.  When PyPI is omitted, then any public packages required either directly or
@@ -245,6 +246,7 @@ flag::
 Note that using this approach, packages newly added to the Pipfile will still be
 included in requirements.txt. If you really want to use Pipfile.lock and
 Pipfile.lock only, you can generate the requirements using::
+
     $ pipenv requirements
     chardet==3.0.4
     requests==2.18.4
@@ -332,15 +334,15 @@ Example::
 
 .. note::
 
-   Each month, `PyUp.io`_ updates the ``safety`` database of
-   insecure Python packages and `makes it available to the
-   community for free <https://pyup.io/safety/>`__. Pipenv
-   makes an API call to retrieve those results and use them
-   each time you run ``pipenv check`` to show you vulnerable
-   dependencies.
+    Each month, `PyUp.io <https://pyup.io>`_ updates the ``safety`` database of
+    insecure Python packages and `makes it available to the
+    community for free <https://pyup.io/safety/>`__. Pipenv
+    makes an API call to retrieve those results and use them
+    each time you run ``pipenv check`` to show you vulnerable
+    dependencies.
 
-   For more up-to-date vulnerability data, you may also use your own safety
-   API key by setting the environment variable ``PIPENV_PYUP_API_KEY``.
+    For more up-to-date vulnerability data, you may also use your own safety
+    API key by setting the environment variable ``PIPENV_PYUP_API_KEY``.
 
 
 ☤ Community Integrations

docs/conf.py

@@ -24,6 +24,13 @@
 with open(os.path.join(here, "..", "pipenv", "__version__.py")) as f:
     exec(f.read(), about)
 
+# Hackery to get the CLI docs to generate
+import click
+
+import pipenv.vendor.click
+
+click.BaseCommand = pipenv.vendor.click.BaseCommand
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -38,7 +45,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
-    "sphinx_click.ext",
+    "sphinx_click",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -124,7 +131,7 @@
 
 
 def setup(app):
-    app.add_stylesheet("custom.css")
+    app.add_css_file("custom.css")
 
 
 # -- Options for HTMLHelp output ------------------------------------------

docs/requirements.txt

@@ -11,15 +11,15 @@ Jinja2==2.10
 MarkupSafe==1.1.0
 pbr==5.1.1
 -e .
-Pygments==2.3.0
+Pygments==2.11.2
 pythonz-bd==1.11.4
 pytz==2018.5
 requests==2.20.1
 resumable-urlretrieve==0.1.5
 six==1.11.0
 snowballstemmer==1.2.1
-Sphinx==1.6.3
-sphinx-click==1.3.0
+Sphinx==4.5.0
+sphinx-click==3.1.0
 sphinxcontrib-spelling==4.2.1
 sphinxcontrib-websupport==1.1.0
 urllib3==1.24.1

news/4778.doc.rst

@@ -0,0 +1,2 @@
+Pipenv CLI documentation generation has been fixed.  It had broke when ``click`` was vendored into the project in
+``2021.11.9`` because by default ``sphinx-click`` could no longer determine the CLI inherited from click.