Re-organize existing documentation into new structure. (#318)

Author: Jon Wayne Parrott

requirements.txt

@@ -1 +1,2 @@
 sphinx==1.5.6
+sphinx_rtd_theme

scripts/linkmonitor/ignored.yaml

@@ -0,0 +1,20 @@
+- url: plugin_discovery.html#plugin-creation-and-discovery
+  reason: named link to first header
+- url: single_source_version.html#single-sourcing-the-project-version
+  reason: named link to first header
+- url: deployment.html#application-deployment
+  reason: named link to first header
+- url: patching.html
+  reason: dropped incomplete topic
+- url: plugin_discovery.html#plugin-creation-and-discovery
+  reason: named link to first header
+- url: deployment.html#application-deployment
+  reason: named link to first header
+- url: additional.html#additional-topics
+  reason: named link to first header
+- url: quickstart.html#quickstart
+  reason: named link to first header
+- url: additional.html#additional-topics
+  reason: named link to first header
+- url: platforms.html#platform-integtation
+  reason: named link to first header

scripts/linkmonitor/inventory.yaml

@@ -15,6 +15,7 @@
 HERE = os.path.abspath(os.path.dirname(__file__))
 INVENTORY_FILENAME = os.path.join(HERE, 'inventory.yaml')
 REDIRECTS_FILENAME = os.path.join(HERE, 'redirects.yaml')
+IGNORED_FILENAME = os.path.join(HERE, 'ignored.yaml')
 ROOT = os.path.abspath(os.path.join(HERE, '..', '..'))
 HTML_DIR = os.path.join(ROOT, 'build', 'html')
 IGNORED_FILES = [
@@ -50,6 +51,9 @@ def find_all_named_anchors_in_files(files):
     links = set()
 
     for filename in files:
+        if filename in ('search.html',):
+            continue
+
         links.add(filename)
         anchors = find_all_named_anchors(filename)
         links.update(anchors)
@@ -80,7 +84,13 @@ def load_redirects():
         return yaml.load(redirects_file)
 
 
-def expand_redirects(redirects, inventory):
+def load_ignored():
+    with io.open(IGNORED_FILENAME, 'r') as ignored_file:
+        raw = yaml.load(ignored_file)
+        return set([entry['url'] for entry in raw])
+
+
+def expand_redirects(redirects, inventory, ignored):
     valid_redirects = set()
     missing_redirects = set()
 
@@ -99,6 +109,9 @@ def expand_redirects(redirects, inventory):
         # destination page. For the example above, new.html needs to have #1
         # #2 and #3 as well.
         for source_link in source_links:
+            if source_link in ignored:
+                continue
+
             dest_link = source_link.replace(from_, redirect['to'])
             if dest_link in inventory:
                 valid_redirects.add(source_link)
@@ -139,9 +152,11 @@ def check_command(args):
     # TODO: Add another file to list currently defined redirects.
     inventory = load_inventory()
     redirects = load_redirects()
+    ignored = load_ignored()
     links = find_links()
 
-    valid_redirects, missing_redirects = expand_redirects(redirects, inventory)
+    valid_redirects, missing_redirects = expand_redirects(
+        redirects, inventory, ignored)
     if missing_redirects:
         print(
             'The following redirects are missing deep link anchors in the '
@@ -152,6 +167,14 @@ def check_command(args):
     missing_links = inventory.difference(links)
     missing_links -= valid_redirects
 
+    ignored_links = set()
+    for link in missing_links:
+        for source_url in ignored:
+            if link.startswith(source_url):
+                ignored_links.add(link)
+
+    missing_links -= ignored_links
+
     if missing_links:
         print('Missing the following deep links:')
         for link in missing_links:

scripts/linkmonitor/linkmonitor.py

@@ -5,3 +5,57 @@
 
 - from: old.html
   to: new.html
+
+- from: additional.html
+  to: guides/index.html
+- from: quickstart.html
+  to: tutorials/index.html
+- from: platforms.html
+  to: guides/installing-scientific-packages.html
+- from: tutorial.html
+  to: tutorials/index.html
+
+- from: installing.html
+  to: tutorials/installing-packages.html
+- from: deployment.html
+  to: discussions/deploying-python-applications.html
+- from: requirements.html
+  to: discussions/install-requires-vs-requirements.html
+- from: pip_easy_install.html
+  to: discussions/pip-vs-easy-install.html
+- from: wheel_egg.html
+  to: discussions/wheel-vs-egg.html
+
+- from: plugin_discovery.html
+  to: guides/creating-and-discovering-plugins.html
+- from: self_hosted_repository.html
+  to: guides/hosting-your-own-index.html
+- from: mirrors.html
+  to: guides/index-mirrors-and-caches.html
+- from: science.html
+  to: guides/installing-scientific-packages.html
+- from: install_requirements_linux.html
+  to: guides/installing-using-linux-tools.html
+- from: multi_version_install.html
+  to: guides/multi-version-installs.html
+- from: extensions.html
+  to: guides/packaging-binary-extensions.html
+- from: namespace_packages.html
+  to: guides/packaging-namespace-packages.html
+- from: single_source_version.html
+  to: guides/single-sourcing-package-version.html
+- from: multiple_python_versions.html
+  to: guides/supporting-multiple-python-versions.html
+- from: appveyor.html
+  to: guides/supporting-windows-using-appveyor.html
+- from: current.html
+  to: guides/tool-recommendations.html
+
+- from: specifications.html
+  to: specifications/index.html
+
+- from: distributing.html
+  to: tutorials/distributing-packages.html
+- from: installing.html
+  to: tutorials/installing-packages.html
+

scripts/linkmonitor/redirects.yaml

@@ -1,7 +1,7 @@
 
-======================
-Application Deployment
-======================
+=============================
+Deploying Python applications
+=============================
 
 :Page Status: Incomplete
 :Last Reviewed: 2014-11-11

source/additional.rst

@@ -0,0 +1,14 @@
+Discussions
+###########
+
+**Discussions** are focused on providing comprehensive information about a
+specific topic. If you're just trying to get stuff done, see
+:doc:`/guides/index`.
+
+.. toctree::
+   :maxdepth: 1
+
+   deploying-python-applications
+   pip-vs-easy-install
+   install-requires-vs-requirements
+   wheel-vs-egg

source/deployment.rst renamed to source/discussions/deploying-python-applications.rst

@@ -1,6 +1,6 @@
-=============================
-Plugin creation and discovery
-=============================
+================================
+Creating and discovering plugins
+================================
 
 :Page Status: Complete
 :Last Reviewed: 2017-04-10
@@ -61,8 +61,8 @@ naming convention.
 Using namespace packages
 ========================
 
-:doc:`Namespace packages <namespace_packages>` can be used to provide a
-convention for where to place plugins and also provides a way to perform
+:doc:`Namespace packages <packaging-namespace-packages>` can be used to provide
+a convention for where to place plugins and also provides a way to perform
 discovery. For example, if you make the sub-package ``myapp.plugins`` a
 namespace package then other :term:`distributions <Distribution Package>` can
 provide modules and packages to that namespace. Once installed, you can use
@@ -117,8 +117,8 @@ to :func:`setup`'s ``packages`` argument instead of using
 
 .. warning:: Namespace packages are a complex feature and there are several
     different ways to create them. It's highly recommended to read the
-    :doc:`namespace_packages` documentation and clearly document which
-    approach is preferred for plugins to your project.
+    :doc:`packaging-namespace-packages` documentation and clearly document
+    which approach is preferred for plugins to your project.
 
 Using package metadata
 ======================

source/discussions/index.rst

@@ -1,7 +1,7 @@
 .. _`Hosting your Own Simple Repository`:
 
 ==================================
-Hosting your Own Simple Repository
+Hosting your own simple repository
 ==================================
 
 :Page Status: Complete

source/requirements.rst renamed to source/discussions/install-requires-vs-requirements.rst

@@ -1,8 +1,8 @@
 .. _`PyPI mirrors and caches`:
 
-=======================
-PyPI mirrors and caches
-=======================
+================================
+Package index mirrors and caches
+================================
 
 :Page Status: Incomplete
 :Last Reviewed: 2014-12-24

source/pip_easy_install.rst renamed to source/discussions/pip-vs-easy-install.rst

@@ -0,0 +1,22 @@
+Guides
+######
+
+**Guides** are focused on accomplishing a specific task and assume that you are
+already familiar with the basics of Python packaging. If you're looking for an
+introduction to packaging, see :doc:`/tutorials/index`.
+
+.. toctree::
+   :maxdepth: 1
+
+   tool-recommendations
+   installing-using-linux-tools
+   installing-scientific-packages
+   multi-version-installs
+   single-sourcing-package-version
+   supporting-multiple-python-versions
+   packaging-binary-extensions
+   supporting-windows-using-appveyor
+   packaging-namespace-packages
+   creating-and-discovering-plugins
+   index-mirrors-and-caches
+   hosting-your-own-index

source/wheel_egg.rst renamed to source/discussions/wheel-vs-egg.rst

@@ -1,8 +1,8 @@
 .. _`Binary Extensions`:
 
-=================
-Binary Extensions
-=================
+===========================
+Packaging binary extensions
+===========================
 
 :Page Status: Incomplete
 :Last Reviewed: 2013-12-08

source/code/appveyor.yml renamed to source/guides/appveyor-sample/appveyor.yml

@@ -1,7 +1,7 @@
 .. _`Single sourcing the version`:
 
 ===================================
-Single-sourcing the Project Version
+Single-sourcing the package version
 ===================================
 
 :Page Status: Complete

source/code/build.cmd renamed to source/guides/appveyor-sample/build.cmd

@@ -68,11 +68,11 @@ Visual Studio used includes 64-bit compilers with no additional setup).
 appveyor.yml
 ------------
 
-.. literalinclude:: code/appveyor.yml
+.. literalinclude:: appveyor-sample/appveyor.yml
    :language: yaml
    :linenos:
 
-This file can be downloaded from `here <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/code/appveyor.yml>`__.
+This file can be downloaded from `here <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/guides/appveyor-sample/appveyor.yml>`__.
 
 The ``appveyor.yml`` file must be located in the root directory of your
 project. It is in ``YAML`` format, and consists of a number of sections.
@@ -123,7 +123,7 @@ environment to use the SDK compiler for 64-bit builds on Python 3.3 and 3.4.
 For projects which do not need a compiler, or which don't support 3.3 or 3.4 on
 64-bit Windows, only the ``appveyor.yml`` file is needed.
 
-`build.cmd <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/code/build.cmd>`__
+`build.cmd <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/guides/ppveyor-sample/build.cmd>`__
 is a Windows batch script that runs a single command in an environment with the
 appropriate compiler for the selected Python version. All you need to do is to
 set the single environment variable ``DISTUTILS_USE_SDK`` to a value of ``1``
@@ -228,9 +228,9 @@ Support scripts
 
 For reference, the SDK setup support script is listed here:
 
-``code/build.cmd``
+``appveyor-sample/build.cmd``
 
-.. literalinclude:: code/build.cmd
+.. literalinclude:: appveyor-sample/build.cmd
    :language: bat
    :linenos:
 

source/plugin_discovery.rst renamed to source/guides/creating-and-discovering-plugins.rst

@@ -1,7 +1,7 @@
 .. _`Tool Recommendations`:
 
 ====================
-Tool Recommendations
+Tool recommendations
 ====================
 
 :Page Status: Complete

source/self_hosted_repository.rst renamed to source/guides/hosting-your-own-index.rst

@@ -16,11 +16,10 @@ This guide is maintained on `github
 .. toctree::
    :maxdepth: 1
 
-   current
-   installing
-   distributing
-   additional
-   specifications
+   tutorials/index
+   guides/index
+   discussions/index
+   specifications/index
    key_projects
    glossary
    support