A start on the documentation (python#30)

A first pass on the documentation, including usage and migration guides.  API docs will be done in a follow up PR.

.travis.yml

@@ -11,11 +11,12 @@ matrix:
     - python: "3.7-dev"
 
 install:
-  - python3 -m pip install --upgrade mypy coverage
+  - python3 -m pip install --upgrade mypy coverage sphinx
 
 script:
   - python3 -m coverage run --rcfile=coverage.ini -m unittest discover
   - mypy --ignore-missing-imports importlib_resources
+  - python3 setup.py build_sphinx
 
 after_success:
   - bash <(curl -s https://codecov.io/bash)

importlib_resources/docs/conf.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# flake8: noqa
+#
+# importlib_resources documentation build configuration file, created by
+# sphinx-quickstart on Thu Nov 30 10:21:00 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.coverage',
+    'sphinx.ext.viewcode']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'importlib_resources'
+copyright = '2017, Brett Cannon, Barry Warsaw'
+author = 'Brett Cannon, Barry Warsaw'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'importlib_resourcesdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'importlib_resources.tex', 'importlib\\_resources Documentation',
+     'Brett Cannon, Barry Warsaw', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'importlib_resources', 'importlib_resources Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'importlib_resources', 'importlib_resources Documentation',
+     author, 'importlib_resources', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    'python': ('https://docs.python.org', None),
+    }

importlib_resources/docs/index.rst

@@ -0,0 +1,44 @@
+================================
+ Welcome to importlib_resources
+================================
+
+``importlib_resources`` is a library which provides for access to *resources*
+in Python packages.  It provides functionality similar to ``pkg_resources``
+`Basic Resource Access`_ API, but without all of the overhead and performance
+problems of ``pkg_resources``.
+
+In our terminology, a *resource* is a file that is located within an
+importable `Python package`_.  Resources can live on the file system, in a zip
+file, or in any place that has a loader_ supporting the appropriate API for
+reading resources.  Directories are not resources.
+
+``importlib_resources`` is a standalone version of the API available for users
+of Python 2.7, or Python 3.4 through 3.6.  It is available in Python 3.7's
+standard library as ``importlib.resources``.  Its API is currently
+`provisional`_.
+
+This documentation includes a general :ref:`usage <using>` guide and a
+:ref:`migration` guide for projects which want to adopt
+``importlib_resources`` instead of ``pkg_resources``.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   using.rst
+   migration.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+.. _`Basic Resource Access`: http://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access
+.. _`provisional`: https://www.python.org/dev/peps/pep-0411/
+.. _`Python package`: https://docs.python.org/3/reference/import.html#packages
+.. _loader: https://docs.python.org/3/reference/import.html#finders-and-loaders

importlib_resources/docs/migration.rst

@@ -0,0 +1,112 @@
+.. _migration:
+
+=================
+ Migration guide
+=================
+
+The following guide will help you migrate common ``pkg_resources`` APIs to
+``importlib_resources``.  Only a small number of the most common APIs are
+supported by ``importlib_resources``, so projects that use other features
+(e.g. entry points) will have to find other solutions.
+``importlib_resources`` primarily supports the following `basic resource
+access`_ APIs:
+
+* ``pkg_resources.resource_filename()``
+* ``pkg_resources.resource_stream()``
+* ``pkg_resources.resource_string()``
+
+Keep in mind that ``pkg_resources`` defines *resources* to include
+directories.  ``importlib_resources`` does not treat directories as resources;
+since only file are allowed as resources, file names in the
+``importlib_resources`` API may *not* include path separators (e.g. slashes).
+
+
+resource_filename()
+===================
+
+``resource_filename()`` is one of the more interesting APIs because it
+guarantees that the return value names a file on the file system.  This means
+that if the resource is in a zip file, ``pkg_resources()`` will extract the
+file and return the name of the temporary file it created.  The problem is
+that ``pkg_resources()`` also *implicitly* cleans up this temporary file,
+without control or its lifetime by the programmer.
+
+``importlib_resources`` takes a different approach.  Its equivalent API is the
+``path()`` function, which returns a context manager providing a
+:py:class:`pathlib.Path` object.  This means users have both the flexibility
+and responsibility to manage the lifetime of the temporary file.  Note though
+that if the resource is *already* on the file system, ``importlib_resources``
+still returns a context manager, but nothing needs to get cleaned up.
+
+Here's an example from ``pkg_resources()``::
+
+    path = pkg_resources.resource_filename('my.package', 'resource.dat')
+
+The best way to convert this is with the following idiom::
+
+    with importlib_resources.path('my.package', 'resource.dat') as path:
+        # Do something with path.  After the with-state exits, any temporary
+        # file created will be immediately cleaned up.
+
+That's all fine is you only need the file temporarily, but what if you need it
+to stick around for a while?  One way of doing this is to use an
+:py:class:`contextlib.ExitStack` instance and manage the resource explicitly::
+
+    from contextlib import ExitStack
+    file_manager = ExitStack()
+    path = file_manager.enter_context(
+        importlib_resources.path('my.package', 'resource.dat'))
+
+Now ``path`` will continue to exist until you explicitly call
+``file_manager.close()``.  What if you want the file to exist until the
+process exits, or you can't pass ``file_manager`` around in your code?  Use an
+:py:mod:`atexit` handler::
+
+    import atexit
+    file_manager = ExitStack()
+    atexit.register(file_manager.close)
+    path = file_manager.enter_context(
+        importlib_resources.path('my.package', 'resource.dat'))
+
+Assuming your Python interpreter exits gracefully, the temporary file will be
+cleaned up when Python exits.
+
+
+resource_stream()
+=================
+
+``pkg_resources.resource_stream()`` returns a readable file-like object opened
+in binary mode.  When you read from the returned file-like object, you get
+bytes.  E.g.::
+
+    with pkg_resources.resource_stream('my.package', 'resource.dat') as fp:
+        my_bytes = fp.read()
+
+The equivalent code in ``importlib_resources`` is pretty straightforward::
+
+    with importlib_resources.open('my.package', 'resource.dat') as fp:
+        my_bytes = fp.read()
+
+
+resource_string()
+=================
+
+In Python 2, ``pkg_resources.resource_string()`` returns the contents of a
+resource as a ``str``.  In Python 3, this function is a misnomer; it actually
+returns the contents of the named resource as ``bytes``.  That's why the
+following example is often written for clarity as::
+
+    from pkg_resources import resource_string as resource_bytes
+    contents = resource_bytes('my.package', 'resource.dat')
+
+This can be easily rewritten like so::
+
+    contents = importlib_resources.read(
+        'my.package', 'resource.dat', encoding=None)
+
+The ``encoding=None`` argument is needed because by default ``read()`` returns
+a ``unicode`` in Python 2 or a ``str`` in Python 3, read and decoded with the
+``utf-8`` encoding.
+
+
+.. _`basic resource access`: http://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access