From 4f676ac9c8df6a860ec6d9c634bb4180c57a9399 Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Fri, 8 Apr 2022 05:36:18 -0400 Subject: [PATCH] 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 | 2 -- docs/advanced.rst | 32 +++++++++++++++++--------------- docs/conf.py | 11 +++++++++-- docs/requirements.txt | 6 +++--- news/4778.doc.rst | 2 ++ 5 files changed, 31 insertions(+), 22 deletions(-) create mode 100644 news/4778.doc.rst diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index aa3e688f..7639b686 100644 --- a/.github/workflows/ci.yaml +++ b/.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/**" diff --git a/docs/advanced.rst b/docs/advanced.rst index e07a8c72..4af7424c 100644 --- a/docs/advanced.rst +++ b/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 `__. 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 `_ updates the ``safety`` database of + insecure Python packages and `makes it available to the + community for free `__. 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 diff --git a/docs/conf.py b/docs/conf.py index a21ef32e..a82e2c1b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -24,6 +24,13 @@ about = {} 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 @@ extensions = [ "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 @@ html_static_path = ["_static"] def setup(app): - app.add_stylesheet("custom.css") + app.add_css_file("custom.css") # -- Options for HTMLHelp output ------------------------------------------ diff --git a/docs/requirements.txt b/docs/requirements.txt index 0e349f9c..2775c190 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/news/4778.doc.rst b/news/4778.doc.rst new file mode 100644 index 00000000..3007d234 --- /dev/null +++ b/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.