revise docs for layout/design

README.md

@@ -25,6 +25,9 @@ Instagram, Medium, Tumblr, Twitter, and WordPress.com.
 An example demo app is deployed at
 [oauth-dropins.appspot.com](http://oauth-dropins.appspot.com/).
 
+[Available on PyPi.](https://pypi.python.org/pypi/oauth-dropins/)
+Install with `pip install oauth-dropins`.
+
 Depends on the
 [App Engine Python SDK](https://developers.google.com/appengine/downloads). All
 other dependencies are handled by pip and enumerated in

README.rst

@@ -1,32 +1,27 @@
-.. image:: https://raw.github.com/snarfed/oauth-dropins/master/oauth_dropins/static/oauth_shiny_128.png
-   :target: https://github.com/snarfed/oauth-dropins
-.. image:: https://circleci.com/gh/snarfed/oauth-dropins.svg?style=svg
-   :target: https://circleci.com/gh/snarfed/oauth-dropins
-.. image:: https://coveralls.io/repos/github/snarfed/oauth-dropins/badge.svg?branch=master
-   :target: https://coveralls.io/github/snarfed/oauth-dropins?branch=master
-
 This is a collection of drop-in
 `Google App Engine <https://appengine.google.com/>`__ request handlers for the
 initial
 `OAuth <http://oauth.net/>`__ client flows for many popular sites, including
 Blogger, Dropbox, Facebook, Flickr, Google+, IndieAuth, Instagram, Medium,
 Twitter, Tumblr, and WordPress.com.
 
-Check out the demo app! https://oauth-dropins.appspot.com/
+An example demo app is deployed at
+`oauth-dropins.appspot.com <http://oauth-dropins.appspot.com/>`__.
+
+`Available on PyPi. <https://pypi.python.org/pypi/oauth-dropins/>`__ Install with ``pip install oauth-dropins``.
 
 `See the GitHub repo <https://github.com/snarfed/oauth-dropins>`__ for full documentation, changelog, etc.
 
 
 Quick start
-===========
+-----------
 
 Here's a full example of using the Facebook drop-in.
 
 1. `Install oauth-dropins into your App Engine app. <https://github.com/snarfed/oauth-dropins#quick-start>`__
 
-1. Put your `Facebook
-   application <https://developers.facebook.com/apps>`__'s ID and secret
-   in two plain text files in your app's root directory,
+1. Put your `Facebook application's <https://developers.facebook.com/apps>`__'s
+   ID and secret in two plain text files in your app's root directory,
    ``facebook_app_id`` and ``facebook_app_secret``. (If you use git,
    you'll probably also want to add them to your ``.gitignore``.)
 
@@ -58,5 +53,3 @@ import the site module you want and follow the same steps. The filenames
 for app keys and secrets also differ by site;
 `appengine_config.py <https://github.com/snarfed/oauth-dropins/blob/master/oauth_dropins/appengine_config.py>`__
 has the full list.
-
-

docs/_templates/description.html

@@ -0,0 +1,46 @@
+<h3>oauth-dropins</h3>
+
+<p>A collection of drop-in
+<a href="https://appengine.google.com/">Google App Engine</a> request handlers
+for the initial <a href="http://oauth.net/">OAuth</a> client flows for many
+popular sites.
+</p>
+
+<p>
+Reference documentation:<br>
+<a href="{{ pathto('source/oauth_dropins') }}">oauth_dropins</a></li><br>
+<a href="{{ pathto('source/oauth_dropins.webutil') }}">webutil</a></li>
+</p>
+
+<p>
+<script async defer src="https://buttons.github.io/buttons.js"></script>
+<a class="github-button"
+   href="https://github.com/snarfed/oauth-dropins"
+   data-icon="octicon-star" data-style="mega"
+   data-count-href="/snarfed/oauth-dropins/stargazers"
+   data-count-api="/repos/snarfed/oauth-dropins#stargazers_count"
+   data-count-aria-label="# stargazers on GitHub"
+   aria-label="Star snarfed/oauth-dropins on GitHub">Star</a>
+<a class="github-button"
+   href="https://github.com/snarfed/oauth-dropins"
+   data-icon="octicon-eye" data-style="mega"
+   data-count-href="/snarfed/oauth-dropins/watchers"
+   data-count-api="/repos/snarfed/oauth-dropins#subscribers_count"
+   data-count-aria-label="# watchers on GitHub"
+   aria-label="Watch snarfed/oauth-dropins on GitHub">Watch</a>
+<br>
+<a href="https://circleci.com/gh/snarfed/oauth-dropins">
+  <img alt="Tests on Circle CI" src="https://circleci.com/gh/snarfed/oauth-dropins.svg?style=svg" />
+</a>
+<a href="https://coveralls.io/github/snarfed/oauth-dropins?branch=master">
+  <img alt="Coverage on Coveralls" src="https://coveralls.io/repos/github/snarfed/oauth-dropins/badge.svg?branch=master" />
+</a>
+</p>
+
+<!-- github ribbon: https://github.com/blog/273-github-ribbons -->
+<a href="https://github.com/snarfed/oauth-dropins">
+  <img style="position: absolute; top: 0; right: 0; border: 0;"
+       src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png"
+       alt="Fork me on GitHub" />
+</a>
+

docs/conf.py

@@ -13,7 +13,6 @@
 
 import sys
 import os
-import shlex
 
 # 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
@@ -98,7 +97,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', '**/test', '**/test_*.py']
+exclude_patterns = ['_build', '**/appengine_config.py', '**/test', '**/test_*.py']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -155,12 +154,12 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = '../oauth_dropins/static/oauth_shiny.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = '../oauth_dropins/static/oauth_16.png'
 
 # 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,
@@ -181,7 +180,10 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+  'index': ['description.html', 'searchbox.html'],
+  '**': ['description.html', 'localtoc.html', 'searchbox.html'],
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -228,7 +230,7 @@
 #html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'oauth-dropinsdoc'
+htmlhelp_basename = 'oauth-dropins-doc'
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/index.rst

@@ -1,23 +1,9 @@
-.. oauth-dropins documentation master file, created by
-   sphinx-quickstart on Fri Oct  7 21:56:55 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+oauth-dropins
+=============
 
-Welcome to oauth-dropins's documentation!
-=========================================
+.. include:: ../README.rst
 
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-   readme
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+Reference documentation:
 
+* :doc:`source/oauth_dropins`
+* :doc:`source/oauth_dropins.webutil`

docs/source/oauth_dropins.rst

@@ -1,157 +1,135 @@
-oauth_dropins package
+oauth_dropins
 =====================
 
-Subpackages
------------
-
 .. toctree::
 
-    oauth_dropins.webutil
-
-Submodules
-----------
-
-oauth_dropins.appengine_config module
--------------------------------------
+    oauth_dropins
 
-.. automodule:: oauth_dropins.appengine_config
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
-oauth_dropins.blogger_v2 module
+blogger_v2
 -------------------------------
 
 .. automodule:: oauth_dropins.blogger_v2
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.disqus module
+disqus
 ---------------------------
 
 .. automodule:: oauth_dropins.disqus
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.dropbox module
+dropbox
 ----------------------------
 
 .. automodule:: oauth_dropins.dropbox
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.facebook module
+facebook
 -----------------------------
 
 .. automodule:: oauth_dropins.facebook
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.flickr module
+flickr
 ---------------------------
 
 .. automodule:: oauth_dropins.flickr
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.flickr_auth module
+flickr_auth
 --------------------------------
 
 .. automodule:: oauth_dropins.flickr_auth
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.googleplus module
+googleplus
 -------------------------------
 
 .. automodule:: oauth_dropins.googleplus
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.handlers module
+handlers
 -----------------------------
 
 .. automodule:: oauth_dropins.handlers
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.indieauth module
+indieauth
 ------------------------------
 
 .. automodule:: oauth_dropins.indieauth
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.instagram module
+instagram
 ------------------------------
 
 .. automodule:: oauth_dropins.instagram
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.medium module
+medium
 ---------------------------
 
 .. automodule:: oauth_dropins.medium
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.models module
+models
 ---------------------------
 
 .. automodule:: oauth_dropins.models
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.tumblr module
+tumblr
 ---------------------------
 
 .. automodule:: oauth_dropins.tumblr
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.twitter module
+twitter
 ----------------------------
 
 .. automodule:: oauth_dropins.twitter
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.twitter_auth module
+twitter_auth
 ---------------------------------
 
 .. automodule:: oauth_dropins.twitter_auth
     :members:
     :undoc-members:
     :show-inheritance:
 
-oauth_dropins.wordpress_rest module
+wordpress_rest
 -----------------------------------
 
 .. automodule:: oauth_dropins.wordpress_rest
     :members:
     :undoc-members:
     :show-inheritance:
-
-
-Module contents
----------------
-
-.. automodule:: oauth_dropins
-    :members:
-    :undoc-members:
-    :show-inheritance: