Updated documentation.

Using 1.0.0 after all.

README.rst

@@ -44,7 +44,7 @@ Changelog
 
 This project adheres to `Semantic Versioning <http://semver.org/>`_.
 
-1.0.0 - Unreleased
+1.0.0 - 2015-08-09
 ------------------
 
 * Initial release.

docs/conf.py

@@ -26,3 +26,13 @@
 html_theme = 'sphinx_rtd_theme'
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 html_title = project
+
+
+# Options for extensions.
+imgur_client_id = '13d3c73555f2190'
+
+
+# Enable the `confval` directive.
+def setup(app):
+    """Called by Sphinx."""
+    app.add_object_type('confval', 'confval', objname='configuration value', indextemplate='pair: %s; config value')

docs/examples.rst

@@ -11,6 +11,9 @@ Inline Roles
 
 Include text entries inline in your paragraphs. These work with images and albums.
 
+Titles and Descriptions
+-----------------------
+
 .. code-block:: rst
 
     * Imgur title of the album below: :imgur-title:`a/hWyW0`

docs/index.rst

@@ -2,7 +2,7 @@
 Imgur Sphinx Extension
 ======================
 
-Todo
+Use `Imgur <http://imgur.com/>`_ images and albums in your Sphinx documents instead of hosting them locally. Save millions on hosting costs!
 
 Project Links
 =============
@@ -18,4 +18,5 @@ Contents
 .. toctree::
     :maxdepth: 2
 
+    usage
     examples

docs/usage.rst

@@ -0,0 +1,75 @@
+.. _usage:
+
+=====
+Usage
+=====
+
+This page documents how to get started with the extension.
+
+Installation
+============
+
+Install the extension with pip:
+
+.. code:: bash
+
+    pip install sphinxcontrib-imgur
+
+Configuration
+=============
+
+If you're just trying to `embed <http://imgur.com/blog/2015/04/07/embed-your-post-anywhere/>`_ albums or images in your
+Sphinx documents you don't need to add anything extra to your ``conf.py``. Just include ``sphinxcontrib.imgur`` in
+``extensions``.
+
+If you'd like to use other features in this extension then you'll need to generate a "Client ID" by going to the
+`Register an Application <https://api.imgur.com/oauth2/addclient>`_ page on Imgur. You'll just need the very basics. As
+of this writing you put in something in Application Name (e.g. your project name or title of your documentation), set
+Authorization Type to "Anonymous usage without user authorization" and whatever for your email and description.
+
+Here is a sample file with the two things you need to do for advanced features:
+
+.. code-block:: python
+
+    # General configuration.
+    author = 'Your Name Here'
+    copyright = '2015, Your Name Here'
+    exclude_patterns = ['_build']
+    extensions = ['sphinxcontrib.imgur']  # Add to this list.
+    master_doc = 'index'
+    project = 'my-cool-project'
+    release = '1.0'
+    version = '1.0'
+
+    # Options for extensions.
+    imgur_client_id = 'abc123def456789'  # Add this line to conf.py.
+
+All Config Options
+==================
+
+.. confval:: imgur_api_cache_ttl
+
+    *Default: 172800 seconds (2 days)*
+
+    Time in seconds before cached Imgur API entries are considered expired. Imgur's API has a request limit (even for
+    simple things like getting an image's title) so this extension caches API replies. This lets you keep making
+    multiple changes in your documentation without bombarding the API. Does not apply to embedded albums/images.
+
+.. confval:: imgur_api_test_response
+
+    Unless you're developing a Sphinx extension you won't need this.
+
+    If defined, should be a nested dictionary. Keys are Imgur image or album (starting with ``a/``) IDs, values are
+    dictionaries whose keys are "title", "description", and other API reply fields and values are what you'd expect. If
+    this option is defined, the Imgur API will always be skipped and any missing Imgur IDs will cause ``KeyError`` to be
+    raised.
+
+.. confval:: imgur_client_id
+
+    Imgur API Client ID to include in request headers. Required for API calls. More information in the section above.
+
+.. confval:: imgur_hide_post_details
+
+    *Default: False*
+
+    The default value of ``hide_post_details`` in embedded albums/images. Overridden in the directive.

sphinxcontrib/imgur/__init__.py

@@ -11,7 +11,7 @@
 
 __author__ = '@Robpol86'
 __license__ = 'MIT'
-__version__ = '0.1.0'
+__version__ = '1.0.0'
 
 
 def event_discover_new_ids(app, doctree):
@@ -69,7 +69,6 @@ def setup(app):
     :returns: Extension version.
     :rtype: dict
     """
-    app.add_config_value('imgur_allow_html', False, True)
     app.add_config_value('imgur_api_cache_ttl', 172800, False)
     app.add_config_value('imgur_api_test_response', None, False)
     app.add_config_value('imgur_client_id', None, False)

tests/test_event_order.py

@@ -20,7 +20,7 @@
     'event_update_imgur_nodes',
 ])
 EXPECTED.append([
-    'event_query_api_update_cache',  # TODO remove
+    'event_query_api_update_cache',
     'event_update_imgur_nodes',
     'event_update_imgur_nodes',
     'event_update_imgur_nodes',