diff --git a/nox.py b/nox.py index 4da95ec35..5ed049b3c 100644 --- a/nox.py +++ b/nox.py @@ -17,6 +17,14 @@ def build(session): session.run('make', 'clean', 'html') +@nox.session +def preview(session): + session.reuse_existing_virtualenv = True + build(session) + session.chdir('build/html') + session.run('python', '-m', 'http.server') + + def linkmonitor(session, command): if not os.path.exists(os.path.join('build', 'html')): session.error('HTML output not available, run nox -s build first.') diff --git a/scripts/linkmonitor/inventory.yaml b/scripts/linkmonitor/inventory.yaml index 13da44925..743204b5b 100644 --- a/scripts/linkmonitor/inventory.yaml +++ b/scripts/linkmonitor/inventory.yaml @@ -5,12 +5,12 @@ appveyor.html#support-script, appveyor.html#support-scripts, appveyor.html#supporting-windows-using-appveyor, appveyor.html#testing-with-tox, contribute.html, contribute.html#audience, contribute.html#contribute-to-this-guide, contribute.html#contributing-style-guide, contribute.html#conventions-and-mechanics, - contribute.html#purpose, contribute.html#scope, - contribute.html#style-guide, contribute.html#voice-and-tone, current.html, current.html#installation-tool-recommendations, - current.html#packaging-tool-recommendations, current.html#tool-recommendations, - deployment.html, deployment.html#application-bundles, deployment.html#application-deployment, - deployment.html#configuration-management, deployment.html#contents, deployment.html#os-packaging-installers, - deployment.html#overview, deployment.html#pynsist, deployment.html#supporting-multiple-hardware-platforms, + contribute.html#purpose, contribute.html#scope, contribute.html#style-guide, contribute.html#voice-and-tone, + current.html, current.html#installation-tool-recommendations, current.html#packaging-tool-recommendations, + current.html#tool-recommendations, deployment.html, deployment.html#application-bundles, + deployment.html#application-deployment, deployment.html#configuration-management, + deployment.html#contents, deployment.html#os-packaging-installers, deployment.html#overview, + deployment.html#pynsist, deployment.html#supporting-multiple-hardware-platforms, deployment.html#windows, discussions/deploying-python-applications.html, discussions/deploying-python-applications.html#application-bundles, discussions/deploying-python-applications.html#configuration-management, discussions/deploying-python-applications.html#contents, discussions/deploying-python-applications.html#deploying-python-applications, discussions/deploying-python-applications.html#os-packaging-installers, @@ -20,17 +20,16 @@ discussions/index.html#discussions, discussions/install-requires-vs-requirements.html, discussions/install-requires-vs-requirements.html#contents, discussions/install-requires-vs-requirements.html#install-requires, discussions/install-requires-vs-requirements.html#install-requires-vs-requirements-files, - discussions/install-requires-vs-requirements.html#requirements-files, - discussions/pip-vs-easy-install.html, discussions/pip-vs-easy-install.html#pip-vs-easy-install, - discussions/wheel-vs-egg.html, discussions/wheel-vs-egg.html#wheel-vs-egg, - distributing.html, distributing.html#author, distributing.html#choosing-a-versioning-scheme, - distributing.html#classifiers, distributing.html#configuring-your-project, distributing.html#console-scripts, - distributing.html#contents, distributing.html#create-an-account, distributing.html#data-files, - distributing.html#date-based-versioning, distributing.html#description, distributing.html#entry-points, - distributing.html#hybrid-schemes, distributing.html#initial-files, distributing.html#install-requires, - distributing.html#keywords, distributing.html#license, distributing.html#local-version-identifiers, - distributing.html#manifest-in, distributing.html#name, distributing.html#package-data, - distributing.html#packages, distributing.html#packaging-and-distributing-projects, + discussions/install-requires-vs-requirements.html#requirements-files, discussions/pip-vs-easy-install.html, + discussions/pip-vs-easy-install.html#pip-vs-easy-install, discussions/wheel-vs-egg.html, + discussions/wheel-vs-egg.html#wheel-vs-egg, distributing.html, distributing.html#author, + distributing.html#choosing-a-versioning-scheme, distributing.html#classifiers, distributing.html#configuring-your-project, + distributing.html#console-scripts, distributing.html#contents, distributing.html#create-an-account, + distributing.html#data-files, distributing.html#date-based-versioning, distributing.html#description, + distributing.html#entry-points, distributing.html#hybrid-schemes, distributing.html#initial-files, + distributing.html#install-requires, distributing.html#keywords, distributing.html#license, + distributing.html#local-version-identifiers, distributing.html#manifest-in, distributing.html#name, + distributing.html#package-data, distributing.html#packages, distributing.html#packaging-and-distributing-projects, distributing.html#packaging-your-project, distributing.html#platform-wheels, distributing.html#pre-release-versioning, distributing.html#pure-python-wheels, distributing.html#readme-rst, distributing.html#requirements-for-packaging-and-distributing, distributing.html#scheme-choices, distributing.html#scripts, distributing.html#semantic-versioning-preferred, @@ -45,39 +44,34 @@ extensions.html#building-binary-extensions, extensions.html#contents, extensions.html#disadvantages, extensions.html#implementing-binary-extensions, extensions.html#publishing-binary-extensions, extensions.html#setting-up-a-build-environment-on-windows, extensions.html#use-cases, - glossary.html, glossary.html#glossary, glossary.html#term-binary-distribution, - glossary.html#term-built-distribution, glossary.html#term-distribution-package, - glossary.html#term-egg, glossary.html#term-extension-module, glossary.html#term-import-package, - glossary.html#term-known-good-set-kgs, glossary.html#term-module, glossary.html#term-package-index, - glossary.html#term-per-project-index, glossary.html#term-project, glossary.html#term-pure-module, - glossary.html#term-python-package-index-pypi, glossary.html#term-python-packaging-authority-pypa, + glossary.html, glossary.html#glossary, glossary.html#term-binary-distribution, glossary.html#term-built-distribution, + glossary.html#term-distribution-package, glossary.html#term-egg, glossary.html#term-extension-module, + glossary.html#term-import-package, glossary.html#term-known-good-set-kgs, glossary.html#term-module, + glossary.html#term-package-index, glossary.html#term-per-project-index, glossary.html#term-project, + glossary.html#term-pure-module, glossary.html#term-python-package-index-pypi, glossary.html#term-python-packaging-authority-pypa, glossary.html#term-release, glossary.html#term-requirement, glossary.html#term-requirement-specifier, glossary.html#term-requirements-file, glossary.html#term-setup-py, glossary.html#term-source-archive, glossary.html#term-source-distribution-or-sdist, glossary.html#term-system-package, glossary.html#term-version-specifier, glossary.html#term-virtual-environment, glossary.html#term-wheel, glossary.html#term-working-set, guides/creating-and-discovering-plugins.html, guides/creating-and-discovering-plugins.html#creating-and-discovering-plugins, - guides/creating-and-discovering-plugins.html#using-namespace-packages, - guides/creating-and-discovering-plugins.html#using-naming-convention, guides/creating-and-discovering-plugins.html#using-package-metadata, - guides/hosting-your-own-index.html, guides/hosting-your-own-index.html#hosting-your-own-simple-repository, - guides/hosting-your-own-index.html#manual-repository, + guides/creating-and-discovering-plugins.html#using-namespace-packages, guides/creating-and-discovering-plugins.html#using-naming-convention, + guides/creating-and-discovering-plugins.html#using-package-metadata, guides/hosting-your-own-index.html, + guides/hosting-your-own-index.html#hosting-your-own-simple-repository, guides/hosting-your-own-index.html#manual-repository, guides/index-mirrors-and-caches.html, guides/index-mirrors-and-caches.html#caching-with-devpi, guides/index-mirrors-and-caches.html#caching-with-pip, guides/index-mirrors-and-caches.html#complete-mirror-with-bandersnatch, guides/index-mirrors-and-caches.html#contents, guides/index-mirrors-and-caches.html#package-index-mirrors-and-caches, - guides/index-mirrors-and-caches.html#pypi-mirrors-and-caches, - guides/index.html, guides/index.html#guides, - guides/installing-scientific-packages.html, guides/installing-scientific-packages.html#building-from-source, + guides/index-mirrors-and-caches.html#pypi-mirrors-and-caches, guides/index.html, + guides/index.html#guides, guides/installing-scientific-packages.html, guides/installing-scientific-packages.html#building-from-source, guides/installing-scientific-packages.html#contents, guides/installing-scientific-packages.html#installing-scientific-packages, guides/installing-scientific-packages.html#linux-distribution-packages, guides/installing-scientific-packages.html#mac-os-x-installers-and-package-managers, - guides/installing-scientific-packages.html#numpy-and-the-science-stack, - guides/installing-scientific-packages.html#scipy-distributions, guides/installing-scientific-packages.html#spack, - guides/installing-scientific-packages.html#the-conda-cross-platform-package-manager, + guides/installing-scientific-packages.html#numpy-and-the-science-stack, guides/installing-scientific-packages.html#scipy-distributions, + guides/installing-scientific-packages.html#spack, guides/installing-scientific-packages.html#the-conda-cross-platform-package-manager, guides/installing-scientific-packages.html#windows-installers, guides/installing-using-linux-tools.html, guides/installing-using-linux-tools.html#arch-linux, guides/installing-using-linux-tools.html#centos-rhel, guides/installing-using-linux-tools.html#debian-ubuntu, guides/installing-using-linux-tools.html#fedora, guides/installing-using-linux-tools.html#installing-pip-setuptools-wheel-with-linux-package-managers, - guides/installing-using-linux-tools.html#opensuse, - guides/multi-version-installs.html, guides/multi-version-installs.html#multi-version-installs, - guides/packaging-binary-extensions.html, + guides/installing-using-linux-tools.html#opensuse, guides/multi-version-installs.html, + guides/multi-version-installs.html#multi-version-installs, guides/packaging-binary-extensions.html, guides/packaging-binary-extensions.html#alternatives-for-low-level-system-access, guides/packaging-binary-extensions.html#alternatives-to-handcoded-accelerator-modules, guides/packaging-binary-extensions.html#alternatives-to-handcoded-wrapper-modules, @@ -89,27 +83,24 @@ guides/packaging-binary-extensions.html#use-cases, guides/packaging-namespace-packages.html, guides/packaging-namespace-packages.html#creating-a-namespace-package, guides/packaging-namespace-packages.html#native-namespace-packages, guides/packaging-namespace-packages.html#packaging-namespace-packages, guides/packaging-namespace-packages.html#pkg-resources-style-namespace-packages, - guides/packaging-namespace-packages.html#pkgutil-style-namespace-packages, - guides/single-sourcing-package-version.html, + guides/packaging-namespace-packages.html#pkgutil-style-namespace-packages, guides/single-sourcing-package-version.html, guides/single-sourcing-package-version.html#single-sourcing-the-package-version, guides/single-sourcing-package-version.html#single-sourcing-the-version, guides/supporting-multiple-python-versions.html, guides/supporting-multiple-python-versions.html#automated-testing-and-continuous-integration, - guides/supporting-multiple-python-versions.html#contents, - guides/supporting-multiple-python-versions.html#supporting-multiple-python-versions, + guides/supporting-multiple-python-versions.html#contents, guides/supporting-multiple-python-versions.html#supporting-multiple-python-versions, guides/supporting-multiple-python-versions.html#tools-for-single-source-python-packages, guides/supporting-multiple-python-versions.html#what-s-in-which-python, guides/supporting-windows-using-appveyor.html, guides/supporting-windows-using-appveyor.html#access-to-the-built-wheels, guides/supporting-windows-using-appveyor.html#adding-appveyor-support-to-your-project, guides/supporting-windows-using-appveyor.html#additional-notes, guides/supporting-windows-using-appveyor.html#appveyor-yml, guides/supporting-windows-using-appveyor.html#automatically-uploading-wheels, guides/supporting-windows-using-appveyor.html#background, guides/supporting-windows-using-appveyor.html#contents, guides/supporting-windows-using-appveyor.html#external-dependencies, - guides/supporting-windows-using-appveyor.html#setting-up, - guides/supporting-windows-using-appveyor.html#support-script, guides/supporting-windows-using-appveyor.html#support-scripts, - guides/supporting-windows-using-appveyor.html#supporting-windows-using-appveyor, + guides/supporting-windows-using-appveyor.html#setting-up, guides/supporting-windows-using-appveyor.html#support-script, + guides/supporting-windows-using-appveyor.html#support-scripts, guides/supporting-windows-using-appveyor.html#supporting-windows-using-appveyor, guides/supporting-windows-using-appveyor.html#testing-with-tox, guides/tool-recommendations.html, guides/tool-recommendations.html#installation-tool-recommendations, guides/tool-recommendations.html#packaging-tool-recommendations, - guides/tool-recommendations.html#tool-recommendations, - index.html, index.html#python-packaging-user-guide, - install_requirements_linux.html, install_requirements_linux.html#arch-linux, install_requirements_linux.html#centos-rhel, + guides/tool-recommendations.html#tool-recommendations, index.html, index.html#get-started, + index.html#learn-more, index.html#python-packaging-user-guide, install_requirements_linux.html, + install_requirements_linux.html#arch-linux, install_requirements_linux.html#centos-rhel, install_requirements_linux.html#debian-ubuntu, install_requirements_linux.html#fedora, install_requirements_linux.html#installing-pip-setuptools-wheel-with-linux-package-managers, install_requirements_linux.html#opensuse, installing.html, installing.html#contents, @@ -128,12 +119,11 @@ key_projects.html#ensurepip, key_projects.html#hashdist, key_projects.html#non-pypa-projects, key_projects.html#packaging, key_projects.html#pex, key_projects.html#pip, key_projects.html#project-summaries, key_projects.html#projects, key_projects.html#pypa-projects, key_projects.html#python-packaging-user-guide, - key_projects.html#setuptools, key_projects.html#spack, - key_projects.html#standard-library-projects, key_projects.html#twine, key_projects.html#venv, - key_projects.html#virtualenv, key_projects.html#warehouse, key_projects.html#wheel, - mirrors.html, mirrors.html#caching-with-devpi, mirrors.html#caching-with-pip, mirrors.html#complete-mirror-with-bandersnatch, - mirrors.html#contents, mirrors.html#pypi-mirrors-and-caches, multi_version_install.html, - multi_version_install.html#multi-version-installs, multiple_python_versions.html, + key_projects.html#setuptools, key_projects.html#spack, key_projects.html#standard-library-projects, + key_projects.html#twine, key_projects.html#venv, key_projects.html#virtualenv, key_projects.html#warehouse, + key_projects.html#wheel, mirrors.html, mirrors.html#caching-with-devpi, mirrors.html#caching-with-pip, + mirrors.html#complete-mirror-with-bandersnatch, mirrors.html#contents, mirrors.html#pypi-mirrors-and-caches, + multi_version_install.html, multi_version_install.html#multi-version-installs, multiple_python_versions.html, multiple_python_versions.html#automated-testing-and-continuous-integration, multiple_python_versions.html#contents, multiple_python_versions.html#supporting-multiple-python-versions, multiple_python_versions.html#tools-for-single-source-python-packages, multiple_python_versions.html#what-s-in-which-python, namespace_packages.html, namespace_packages.html#creating-a-namespace-package, @@ -164,11 +154,10 @@ specifications/index.html#description-content-type, specifications/index.html#package-distribution-metadata, specifications/index.html#package-index-interfaces, specifications/index.html#platform-compatibility-tags, specifications/index.html#provides-extra-multiple-use, specifications/index.html#pypa-specifications, - specifications/index.html#recording-installed-distributions, - specifications/index.html#simple-repository-api, specifications/index.html#source-distribution-format, - specifications/index.html#specifications, specifications/index.html#version-specifiers, - support.html, support.html#how-to-get-support, tutorial.html, - tutorials/distributing-packages.html, tutorials/distributing-packages.html#author, + specifications/index.html#recording-installed-distributions, specifications/index.html#simple-repository-api, + specifications/index.html#source-distribution-format, specifications/index.html#specifications, + specifications/index.html#version-specifiers, support.html, support.html#how-to-get-support, + tutorial.html, tutorials/distributing-packages.html, tutorials/distributing-packages.html#author, tutorials/distributing-packages.html#choosing-a-versioning-scheme, tutorials/distributing-packages.html#classifiers, tutorials/distributing-packages.html#configuring-your-project, tutorials/distributing-packages.html#console-scripts, tutorials/distributing-packages.html#contents, tutorials/distributing-packages.html#create-an-account, @@ -183,26 +172,24 @@ tutorials/distributing-packages.html#platform-wheels, tutorials/distributing-packages.html#pre-release-versioning, tutorials/distributing-packages.html#pure-python-wheels, tutorials/distributing-packages.html#readme-rst, tutorials/distributing-packages.html#requirements-for-packaging-and-distributing, - tutorials/distributing-packages.html#scheme-choices, - tutorials/distributing-packages.html#scripts, tutorials/distributing-packages.html#semantic-versioning-preferred, - tutorials/distributing-packages.html#serial-versioning, tutorials/distributing-packages.html#setup-args, - tutorials/distributing-packages.html#setup-cfg, tutorials/distributing-packages.html#setup-name, - tutorials/distributing-packages.html#setup-py, tutorials/distributing-packages.html#source-distributions, - tutorials/distributing-packages.html#standards-compliance-for-interoperability, + tutorials/distributing-packages.html#scheme-choices, tutorials/distributing-packages.html#scripts, + tutorials/distributing-packages.html#semantic-versioning-preferred, tutorials/distributing-packages.html#serial-versioning, + tutorials/distributing-packages.html#setup-args, tutorials/distributing-packages.html#setup-cfg, + tutorials/distributing-packages.html#setup-name, tutorials/distributing-packages.html#setup-py, + tutorials/distributing-packages.html#source-distributions, tutorials/distributing-packages.html#standards-compliance-for-interoperability, tutorials/distributing-packages.html#universal-wheels, tutorials/distributing-packages.html#upload-your-distributions, tutorials/distributing-packages.html#uploading-your-project-to-pypi, tutorials/distributing-packages.html#url, tutorials/distributing-packages.html#version, tutorials/distributing-packages.html#wheels, tutorials/distributing-packages.html#working-in-development-mode, tutorials/distributing-packages.html#your-package, - tutorials/index.html, tutorials/index.html#tutorials, - tutorials/installing-packages.html, tutorials/installing-packages.html#contents, - tutorials/installing-packages.html#creating-and-using-virtual-environments, tutorials/installing-packages.html#creating-virtual-environments, - tutorials/installing-packages.html#install-pip-setuptools-and-wheel, tutorials/installing-packages.html#installing-from-a-local-src-tree, - tutorials/installing-packages.html#installing-from-local-archives, tutorials/installing-packages.html#installing-from-other-indexes, - tutorials/installing-packages.html#installing-from-other-sources, tutorials/installing-packages.html#installing-from-pypi, - tutorials/installing-packages.html#installing-from-vcs, tutorials/installing-packages.html#installing-packages, - tutorials/installing-packages.html#installing-prereleases, tutorials/installing-packages.html#installing-requirements, - tutorials/installing-packages.html#installing-setuptools-extras, tutorials/installing-packages.html#installing-to-the-user-site, - tutorials/installing-packages.html#optionally-create-a-virtual-environment, tutorials/installing-packages.html#requirements-files, - tutorials/installing-packages.html#requirements-for-installing-packages, + tutorials/index.html, tutorials/index.html#tutorials, tutorials/installing-packages.html, + tutorials/installing-packages.html#contents, tutorials/installing-packages.html#creating-and-using-virtual-environments, + tutorials/installing-packages.html#creating-virtual-environments, tutorials/installing-packages.html#install-pip-setuptools-and-wheel, + tutorials/installing-packages.html#installing-from-a-local-src-tree, tutorials/installing-packages.html#installing-from-local-archives, + tutorials/installing-packages.html#installing-from-other-indexes, tutorials/installing-packages.html#installing-from-other-sources, + tutorials/installing-packages.html#installing-from-pypi, tutorials/installing-packages.html#installing-from-vcs, + tutorials/installing-packages.html#installing-packages, tutorials/installing-packages.html#installing-prereleases, + tutorials/installing-packages.html#installing-requirements, tutorials/installing-packages.html#installing-setuptools-extras, + tutorials/installing-packages.html#installing-to-the-user-site, tutorials/installing-packages.html#optionally-create-a-virtual-environment, + tutorials/installing-packages.html#requirements-files, tutorials/installing-packages.html#requirements-for-installing-packages, tutorials/installing-packages.html#source-distributions-vs-wheels, tutorials/installing-packages.html#upgrading-packages, tutorials/installing-packages.html#use-pip-for-installing, wheel_egg.html, wheel_egg.html#wheel-vs-egg] diff --git a/source/conf.py b/source/conf.py index 0129a8805..a0e8df7d9 100644 --- a/source/conf.py +++ b/source/conf.py @@ -130,6 +130,7 @@ html_theme_options = { 'collapsiblesidebar': True, 'externalrefs': True, + 'navigation_depth': 2, 'issues_url': 'https://github.com/pypa/python-packaging-user-guide/issues' } @@ -184,7 +185,7 @@ # Custom sidebar templates, filenames relative to this file. html_sidebars = { '**': ['localtoc.html', 'relations.html'], - 'index': ['globaltoc.html'] + 'index': ['localtoc.html'] } # Additional templates that should be rendered to pages, maps page names to diff --git a/source/index.rst b/source/index.rst index 0f292ef10..688620982 100644 --- a/source/index.rst +++ b/source/index.rst @@ -2,19 +2,9 @@ Python Packaging User Guide =========================== -The "Python Packaging User Guide" (PyPUG) aims to be the authoritative resource -on how to package, publish, and install Python projects using current tools. - -To follow the development of Python packaging, see the `Python -Packaging Authority `_. - -This guide is maintained on `github -`_. - -.. _docs.python.org: http://docs.python.org - .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + :hidden: tutorials/index guides/index @@ -24,3 +14,31 @@ This guide is maintained on `github glossary support contribute + +Welcome to the *Python Packaging User Guide*, a collection of tutorials and +references to help you distribute and install Python packages with modern +tools. + +This guide is maintained on `GitHub`_ by the `Python Packaging Authority`_. We +happily accept any :doc:`contributions and feedback `. 😊 + +.. _GitHub: https://github.com/pypa/python-packaging-user-guide> +.. _Python Packaging Authority: https://pypa.io + +Get started +=========== + +If you want to learn how to install packages, see the :doc:`tutorial on installing packages `. + +If you want to learn how to package and distribute your projects, see the :doc:`tutorial on packaging and distributing ` + +Learn more +========== + +Beyond our :doc:`tutorials/index`, this guide has several other resources: + +* :doc:`guides/index` for walk throughs, such as :doc:`guides/installing-using-linux-tools` or :doc:`guides/packaging-binary-extensions` +* :doc:`discussions/index` for in-depth references on topics such as :doc:`discussions/deploying-python-applications` or :doc:`discussions/pip-vs-easy-install` +* :doc:`specifications/index` for packaging interoperability specifications + +Additionally, there is a list of :doc:`other projects ` maintained by members of the Python Packaging Authority.