Start seriously working on documentation

README.rst

@@ -2,12 +2,12 @@ rfc3986
 =======
 
 A Python implementation of `RFC 3986`_ including validation and authority 
-parsing. Coming soon: `Reference Resolution <http://tools.ietf.org/html/rfc3986#section-5>`_.
+parsing.
 
 Installation
 ------------
 
-Simply use pip to install ``rfc3986`` like so::
+Use pip to install ``rfc3986`` like so::
 
     pip install rfc3986
 

docs/source/api-ref/uri.rst

@@ -0,0 +1,19 @@
+===============
+ URI Submodule
+===============
+
+.. autoclass:: rfc3986.uri.URIReference
+
+.. automethod:: rfc3986.uri.URIReference.from_string
+
+.. automethod:: rfc3986.uri.URIReference.unsplit
+
+.. automethod:: rfc3986.uri.URIReference.resolve_with
+
+.. automethod:: rfc3986.uri.URIReference.copy_with
+
+.. automethod:: rfc3986.uri.URIReference.normalize
+
+.. automethod:: rfc3986.uri.URIReference.is_absolute
+
+.. automethod:: rfc3986.uri.URIReference.authority_info

docs/source/conf.py

@@ -26,14 +26,20 @@
 # If your documentation needs a minimal Sphinx version, state it here.
 #
 # needs_sphinx = '1.0'
+rst_epilog = """
+.. |rfc3986| replace:: :mod:`rfc3986`
+"""
 
 # 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',
+extensions = [
+    'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.coverage']
+    'sphinx.ext.coverage',
+    'sphinx-prompt',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -156,7 +162,5 @@ texinfo_documents = [
 ]
 
 
-
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}

docs/source/index.rst

@@ -1,20 +1,27 @@
-.. rfc3986 documentation master file, created by
-   sphinx-quickstart on Tue Mar 14 07:06:46 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+=========
+ rfc3986
+=========
 
-Welcome to rfc3986's documentation!
-===================================
+|rfc3986| is a Python implementation of :rfc:`3986` including validation and 
+authority parsing.
+
+The maintainers strongly suggest using `pip`_ to install |rfc3986|. For 
+example,
+
+.. prompt:: bash
+
+    pip install rfc3986
+    python -m pip install rfc3986
+    python3.6 -m pip install rfc3986
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+    :maxdepth: 2
+    :caption: Contents:
+
+    narrative
+    api-ref/uri
 
 
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. links
+.. _pip:
+    https://pypi.python.org/pypi/pip/

docs/source/narrative.rst

@@ -0,0 +1,27 @@
+====================
+ User Documentation
+====================
+
+|rfc3986| has several API features and convenience methods. The core of
+|rfc3986|'s API revolves around parsing, validating, and building URIs.
+
+There is an API to provide compatibility with :mod:`urllib.parse`, there is an 
+API to parse a URI as a URI Reference, there's an API to provide validation of 
+URIs, and finally there's an API to build URIs.
+
+.. note::
+
+    There's presently no support for IRIs as defined in :rfc:`3987`.
+
+|rfc3986| parses URIs much differently from :mod:`urllib.parse` so users may
+see some subtle differences with very specific URLs that contain rough
+edgecases. Regardless, we do our best to implement the same API so you should
+be able to seemlessly swap |rfc3986| for ``urlparse``.
+
+
+.. toctree::
+    :maxdepth: 2
+
+    user/parsing
+    user/validating
+    user/building

docs/source/user/parsing.rst

@@ -0,0 +1,9 @@
+===============
+ Parsing a URI
+===============
+
+There are two ways to parse a URI with |rfc3986|
+
+#. :meth:`rfc3986.uri.URIReference.from_string`
+
+#.

src/rfc3986/uri.py

@@ -444,14 +444,3 @@ class URIReference(namedtuple('URIReference', misc.URI_COMPONENTS)):
         uri = self._replace(**attributes)
         uri.encoding = self.encoding
         return uri
-
-    def validate(self, validator):
-        """Validate the URI using the configured validator.
-
-        :param validator:
-            Instantiated and configured Validator.
-        :type validator:
-            rfc3986.validators.Validator
-        :raises ValidatorErrors:
-            In the event of one or more errors in validation.
-        """

tox.ini

@@ -37,8 +37,9 @@ commands =
 [testenv:docs]
 deps =
     sphinx>=1.3.0
+    sphinx-prompt
 commands =
-    sphinx-build -E -c docs -b html docs/source/ docs/build/html
+    sphinx-build -E -c docs/source/ -b html docs/source/ docs/build/html
 
 [testenv:readme]
 deps =