From 4a6276bfc98d17d523c69e9739e82eeb900a440b Mon Sep 17 00:00:00 2001 From: Srinivas Nyayapati Date: Thu, 6 Aug 2020 16:06:10 -0400 Subject: [PATCH] Add tabs to ref docs --- docs/html/reference/pip_cache.rst | 10 +- docs/html/reference/pip_check.rst | 79 +++++++++--- docs/html/reference/pip_config.rst | 10 +- docs/html/reference/pip_debug.rst | 10 +- docs/html/reference/pip_hash.rst | 47 +++++-- docs/html/reference/pip_list.rst | 201 +++++++++++++++++++++++------ docs/html/reference/pip_search.rst | 30 ++++- docs/html/reference/pip_show.rst | 176 +++++++++++++++++-------- docs/html/reference/pip_wheel.rst | 75 +++++++++-- 9 files changed, 500 insertions(+), 138 deletions(-) diff --git a/docs/html/reference/pip_cache.rst b/docs/html/reference/pip_cache.rst index 8ad99f65c..35e0dfcad 100644 --- a/docs/html/reference/pip_cache.rst +++ b/docs/html/reference/pip_cache.rst @@ -9,7 +9,15 @@ pip cache Usage ***** -.. pip-command-usage:: cache +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: cache "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: cache "py -m pip" Description *********** diff --git a/docs/html/reference/pip_check.rst b/docs/html/reference/pip_check.rst index a12d5b3ec..07d700475 100644 --- a/docs/html/reference/pip_check.rst +++ b/docs/html/reference/pip_check.rst @@ -10,7 +10,15 @@ pip check Usage ===== -.. pip-command-usage:: check +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: check "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: check "py -m pip" Description @@ -24,27 +32,66 @@ Examples #. If all dependencies are compatible: - :: + .. tabs:: - $ pip check - No broken requirements found. - $ echo $? - 0 + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip check + No broken requirements found. + $ echo $? + 0 + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip check + No broken requirements found. + C:\> echo %errorlevel% + 0 #. If a package is missing: - :: + .. tabs:: - $ pip check - pyramid 1.5.2 requires WebOb, which is not installed. - $ echo $? - 1 + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip check + pyramid 1.5.2 requires WebOb, which is not installed. + $ echo $? + 1 + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip check + pyramid 1.5.2 requires WebOb, which is not installed. + C:\> echo %errorlevel% + 1 #. If a package has the wrong version: - :: + .. tabs:: - $ pip check - pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8. - $ echo $? - 1 + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip check + pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8. + $ echo $? + 1 + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip check + pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8. + C:\> echo %errorlevel% + 1 diff --git a/docs/html/reference/pip_config.rst b/docs/html/reference/pip_config.rst index 70d9406c5..d9bf0afc8 100644 --- a/docs/html/reference/pip_config.rst +++ b/docs/html/reference/pip_config.rst @@ -11,7 +11,15 @@ pip config Usage ===== -.. pip-command-usage:: config +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: config "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: config "py -m pip" Description diff --git a/docs/html/reference/pip_debug.rst b/docs/html/reference/pip_debug.rst index da147bcf2..2ef98228a 100644 --- a/docs/html/reference/pip_debug.rst +++ b/docs/html/reference/pip_debug.rst @@ -10,7 +10,15 @@ pip debug Usage ===== -.. pip-command-usage:: debug +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: debug "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: debug "py -m pip" .. warning:: diff --git a/docs/html/reference/pip_hash.rst b/docs/html/reference/pip_hash.rst index dbf1f3e94..7ed39280c 100644 --- a/docs/html/reference/pip_hash.rst +++ b/docs/html/reference/pip_hash.rst @@ -10,7 +10,15 @@ pip hash Usage ===== -.. pip-command-usage:: hash +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: hash "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: hash "py -m pip" Description @@ -39,13 +47,32 @@ Options Example ======= -Compute the hash of a downloaded archive:: +Compute the hash of a downloaded archive: - $ pip download SomePackage - Collecting SomePackage - Downloading SomePackage-2.2.tar.gz - Saved ./pip_downloads/SomePackage-2.2.tar.gz - Successfully downloaded SomePackage - $ pip hash ./pip_downloads/SomePackage-2.2.tar.gz - ./pip_downloads/SomePackage-2.2.tar.gz: - --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip download SomePackage + Collecting SomePackage + Downloading SomePackage-2.2.tar.gz + Saved ./pip_downloads/SomePackage-2.2.tar.gz + Successfully downloaded SomePackage + $ python -m pip hash ./pip_downloads/SomePackage-2.2.tar.gz + ./pip_downloads/SomePackage-2.2.tar.gz: + --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip download SomePackage + Collecting SomePackage + Downloading SomePackage-2.2.tar.gz + Saved ./pip_downloads/SomePackage-2.2.tar.gz + Successfully downloaded SomePackage + C:\> py -m pip hash ./pip_downloads/SomePackage-2.2.tar.gz + ./pip_downloads/SomePackage-2.2.tar.gz: + --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 diff --git a/docs/html/reference/pip_list.rst b/docs/html/reference/pip_list.rst index 15d0920a7..bfdef9ebe 100644 --- a/docs/html/reference/pip_list.rst +++ b/docs/html/reference/pip_list.rst @@ -10,7 +10,15 @@ pip list Usage ===== -.. pip-command-usage:: list +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: list "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: list "py -m pip" Description @@ -32,75 +40,182 @@ Examples #. List installed packages. - :: + .. tabs:: - $ pip list - docutils (0.10) - Jinja2 (2.7.2) - MarkupSafe (0.18) - Pygments (1.6) - Sphinx (1.2.1) + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip list + docutils (0.10) + Jinja2 (2.7.2) + MarkupSafe (0.18) + Pygments (1.6) + Sphinx (1.2.1) + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip list + docutils (0.10) + Jinja2 (2.7.2) + MarkupSafe (0.18) + Pygments (1.6) + Sphinx (1.2.1) #. List outdated packages (excluding editables), and the latest version available. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip list --outdated + docutils (Current: 0.10 Latest: 0.11) + Sphinx (Current: 1.2.1 Latest: 1.2.2) + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip list --outdated + docutils (Current: 0.10 Latest: 0.11) + Sphinx (Current: 1.2.1 Latest: 1.2.2) - $ pip list --outdated - docutils (Current: 0.10 Latest: 0.11) - Sphinx (Current: 1.2.1 Latest: 1.2.2) #. List installed packages with column formatting. - :: + .. tabs:: - $ pip list --format columns - Package Version - ------- ------- - docopt 0.6.2 - idlex 1.13 - jedi 0.9.0 + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip list --format columns + Package Version + ------- ------- + docopt 0.6.2 + idlex 1.13 + jedi 0.9.0 + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip list --format columns + Package Version + ------- ------- + docopt 0.6.2 + idlex 1.13 + jedi 0.9.0 #. List outdated packages with column formatting. - :: + .. tabs:: - $ pip list -o --format columns - Package Version Latest Type - ---------- ------- ------ ----- - retry 0.8.1 0.9.1 wheel - setuptools 20.6.7 21.0.0 wheel + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip list -o --format columns + Package Version Latest Type + ---------- ------- ------ ----- + retry 0.8.1 0.9.1 wheel + setuptools 20.6.7 21.0.0 wheel + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip list -o --format columns + Package Version Latest Type + ---------- ------- ------ ----- + retry 0.8.1 0.9.1 wheel + setuptools 20.6.7 21.0.0 wheel #. List packages that are not dependencies of other packages. Can be combined with other options. - :: + .. tabs:: - $ pip list --outdated --not-required - docutils (Current: 0.10 Latest: 0.11) + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip list --outdated --not-required + docutils (Current: 0.10 Latest: 0.11) + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip list --outdated --not-required + docutils (Current: 0.10 Latest: 0.11) #. Use legacy formatting - :: + .. tabs:: - $ pip list --format=legacy - colorama (0.3.7) - docopt (0.6.2) - idlex (1.13) - jedi (0.9.0) + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip list --format=legacy + colorama (0.3.7) + docopt (0.6.2) + idlex (1.13) + jedi (0.9.0) + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip list --format=legacy + colorama (0.3.7) + docopt (0.6.2) + idlex (1.13) + jedi (0.9.0) #. Use json formatting - :: + .. tabs:: - $ pip list --format=json - [{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ... + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip list --format=json + [{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ... + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip list --format=json + [{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ... #. Use freeze formatting - :: + .. tabs:: - $ pip list --format=freeze - colorama==0.3.7 - docopt==0.6.2 - idlex==1.13 - jedi==0.9.0 + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip list --format=freeze + colorama==0.3.7 + docopt==0.6.2 + idlex==1.13 + jedi==0.9.0 + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip list --format=freeze + colorama==0.3.7 + docopt==0.6.2 + idlex==1.13 + jedi==0.9.0 diff --git a/docs/html/reference/pip_search.rst b/docs/html/reference/pip_search.rst index db1bd2be8..e0fc3e25b 100644 --- a/docs/html/reference/pip_search.rst +++ b/docs/html/reference/pip_search.rst @@ -10,7 +10,15 @@ pip search Usage ===== -.. pip-command-usage:: search +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: search "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: search "py -m pip" Description @@ -30,8 +38,20 @@ Examples #. Search for "peppercorn" - :: + .. tabs:: - $ pip search peppercorn - pepperedform - Helpers for using peppercorn with formprocess. - peppercorn - A library for converting a token stream into [...] + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip search peppercorn + pepperedform - Helpers for using peppercorn with formprocess. + peppercorn - A library for converting a token stream into [...] + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip search peppercorn + pepperedform - Helpers for using peppercorn with formprocess. + peppercorn - A library for converting a token stream into [...] diff --git a/docs/html/reference/pip_show.rst b/docs/html/reference/pip_show.rst index e9568b6b0..ae9182f54 100644 --- a/docs/html/reference/pip_show.rst +++ b/docs/html/reference/pip_show.rst @@ -10,7 +10,15 @@ pip show Usage ===== -.. pip-command-usage:: show +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: show "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: show "py -m pip" Description @@ -30,58 +38,124 @@ Examples #. Show information about a package: - :: + .. tabs:: - $ pip show sphinx - Name: Sphinx - Version: 1.4.5 - Summary: Python documentation generator - Home-page: http://sphinx-doc.org/ - Author: Georg Brandl - Author-email: georg@python.org - License: BSD - Location: /my/env/lib/python2.7/site-packages - Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip show sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip show sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six #. Show all information about a package - :: + .. tabs:: - $ pip show --verbose sphinx - Name: Sphinx - Version: 1.4.5 - Summary: Python documentation generator - Home-page: http://sphinx-doc.org/ - Author: Georg Brandl - Author-email: georg@python.org - License: BSD - Location: /my/env/lib/python2.7/site-packages - Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six - Metadata-Version: 2.0 - Installer: - Classifiers: - Development Status :: 5 - Production/Stable - Environment :: Console - Environment :: Web Environment - Intended Audience :: Developers - Intended Audience :: Education - License :: OSI Approved :: BSD License - Operating System :: OS Independent - Programming Language :: Python - Programming Language :: Python :: 2 - Programming Language :: Python :: 3 - Framework :: Sphinx - Framework :: Sphinx :: Extension - Framework :: Sphinx :: Theme - Topic :: Documentation - Topic :: Documentation :: Sphinx - Topic :: Text Processing - Topic :: Utilities - Entry-points: - [console_scripts] - sphinx-apidoc = sphinx.apidoc:main - sphinx-autogen = sphinx.ext.autosummary.generate:main - sphinx-build = sphinx:main - sphinx-quickstart = sphinx.quickstart:main - [distutils.commands] - build_sphinx = sphinx.setup_command:BuildDoc + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip show --verbose sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + Metadata-Version: 2.0 + Installer: + Classifiers: + Development Status :: 5 - Production/Stable + Environment :: Console + Environment :: Web Environment + Intended Audience :: Developers + Intended Audience :: Education + License :: OSI Approved :: BSD License + Operating System :: OS Independent + Programming Language :: Python + Programming Language :: Python :: 2 + Programming Language :: Python :: 3 + Framework :: Sphinx + Framework :: Sphinx :: Extension + Framework :: Sphinx :: Theme + Topic :: Documentation + Topic :: Documentation :: Sphinx + Topic :: Text Processing + Topic :: Utilities + Entry-points: + [console_scripts] + sphinx-apidoc = sphinx.apidoc:main + sphinx-autogen = sphinx.ext.autosummary.generate:main + sphinx-build = sphinx:main + sphinx-quickstart = sphinx.quickstart:main + [distutils.commands] + build_sphinx = sphinx.setup_command:BuildDoc + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip show --verbose sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + Metadata-Version: 2.0 + Installer: + Classifiers: + Development Status :: 5 - Production/Stable + Environment :: Console + Environment :: Web Environment + Intended Audience :: Developers + Intended Audience :: Education + License :: OSI Approved :: BSD License + Operating System :: OS Independent + Programming Language :: Python + Programming Language :: Python :: 2 + Programming Language :: Python :: 3 + Framework :: Sphinx + Framework :: Sphinx :: Extension + Framework :: Sphinx :: Theme + Topic :: Documentation + Topic :: Documentation :: Sphinx + Topic :: Text Processing + Topic :: Utilities + Entry-points: + [console_scripts] + sphinx-apidoc = sphinx.apidoc:main + sphinx-autogen = sphinx.ext.autosummary.generate:main + sphinx-build = sphinx:main + sphinx-quickstart = sphinx.quickstart:main + [distutils.commands] + build_sphinx = sphinx.setup_command:BuildDoc diff --git a/docs/html/reference/pip_wheel.rst b/docs/html/reference/pip_wheel.rst index dc32dda46..0a11c6e25 100644 --- a/docs/html/reference/pip_wheel.rst +++ b/docs/html/reference/pip_wheel.rst @@ -11,7 +11,15 @@ pip wheel Usage ===== -.. pip-command-usage:: wheel +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: wheel "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: wheel "py -m pip" Description @@ -24,9 +32,22 @@ Build System Interface ---------------------- In order for pip to build a wheel, ``setup.py`` must implement the -``bdist_wheel`` command with the following syntax:: +``bdist_wheel`` command with the following syntax: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python setup.py bdist_wheel -d TARGET + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py setup.py bdist_wheel -d TARGET - python setup.py bdist_wheel -d TARGET This command must create a wheel compatible with the invoking Python interpreter, and save that wheel in the directory TARGET. @@ -39,9 +60,22 @@ Customising the build It is possible using ``--global-option`` to include additional build commands with their arguments in the ``setup.py`` command. This is currently the only way to influence the building of C extensions from the command line. For -example:: +example: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip wheel --global-option bdist_ext --global-option -DFOO wheel + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip wheel --global-option bdist_ext --global-option -DFOO wheel - pip wheel --global-option bdist_ext --global-option -DFOO wheel will result in a build command of @@ -69,13 +103,34 @@ Examples #. Build wheels for a requirement (and all its dependencies), and then install - :: + .. tabs:: - $ pip wheel --wheel-dir=/tmp/wheelhouse SomePackage - $ pip install --no-index --find-links=/tmp/wheelhouse SomePackage + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip wheel --wheel-dir=/tmp/wheelhouse SomePackage + $ python -m pip install --no-index --find-links=/tmp/wheelhouse SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip wheel --wheel-dir=/tmp/wheelhouse SomePackage + C:\> py -m pip install --no-index --find-links=/tmp/wheelhouse SomePackage #. Build a wheel for a package from source - :: + .. tabs:: - $ pip wheel --no-binary SomePackage SomePackage + .. group-tab:: Unix/macOS + + .. code-block:: shell + + $ python -m pip wheel --no-binary SomePackage SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + C:\> py -m pip wheel --no-binary SomePackage SomePackage