Create new, simpler packaging tutorial (#498)

Move the existing tutorial into guides/distributing-packages-using-setuptools to be cleaned up later.

nox.py

@@ -8,18 +8,23 @@
 
 
 @nox.session
-def build(session):
+def build(session, autobuild=False):
     session.interpreter = 'python3.6'
     session.install('-r', 'requirements.txt')
     # Treat warnings as errors.
     session.env['SPHINXOPTS'] = '-W'
     session.run(shutil.rmtree, 'build', ignore_errors=True)
-    session.run('sphinx-build', '-W', '-b', 'html', 'source', 'build')
+
+    if autobuild:
+        command = 'sphinx-autobuild'
+    else:
+        command = 'sphinx-build'
+
+    session.run(command, '-W', '-b', 'html', 'source', 'build')
 
 
 @nox.session
 def preview(session):
     session.reuse_existing_virtualenv = True
-    build(session)
-    session.chdir('build')
-    session.run('python', '-m', 'http.server')
+    session.install("sphinx-autobuild")
+    build(session, autobuild=True)

requirements.txt

@@ -1,3 +1,4 @@
 sphinx==1.7.4
+sphinx-autobuild==0.7.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

source/tutorials/distributing-packages.rst → source/guides/distributing-packages-using-setuptools.rst

@@ -6,7 +6,7 @@ Packaging and distributing projects
 
 This section covers the basics of how to configure, package and distribute your
 own Python projects.  It assumes that you are already familiar with the contents
-of the :doc:`installing-packages` page.
+of the :doc:`/tutorials/installing-packages` page.
 
 The section does *not* aim to cover best practices for Python project
 development as a whole.  For example, it does not provide guidance or tool

source/guides/index.rst

@@ -13,6 +13,7 @@ introduction to packaging, see :doc:`/tutorials/index`.
    installing-using-linux-tools
    installing-scientific-packages
    multi-version-installs
+   distributing-packages-using-setuptools
    single-sourcing-package-version
    supporting-multiple-python-versions
    dropping-older-python-versions

source/index.rst

@@ -40,7 +40,7 @@ covered in our :doc:`tutorials/index` section:
 * to learn how to manage dependencies in a version controlled project, see the
   :doc:`tutorial on managing application dependencies <tutorials/managing-dependencies>`.
 * to learn how to package and distribute your projects, see the
-  :doc:`tutorial on packaging and distributing <tutorials/distributing-packages>`
+  :doc:`tutorial on packaging and distributing <tutorials/packaging-projects>`
 
 Learn more
 ==========

source/key_projects.rst

@@ -280,6 +280,8 @@ a complimentary command line tool to drive packaging, testing and release
 activities with Python.
 
 
+.. _flit:
+
 flit
 ====
 

source/tutorials/index.rst

@@ -10,4 +10,4 @@ topics, see :doc:`/guides/index`.
 
     installing-packages
     managing-dependencies
-    distributing-packages
+    packaging-projects