Improve docs and unify with readme

.gitignore

@@ -44,3 +44,6 @@ nosetests.xml
 
 # Docs
 docs/_build
+
+# LO lock file
+.~lock.*

README.md

@@ -4,20 +4,40 @@
 
 # Social-Federation
 
-Python library to abstract social federation protocols. Currently supports a subset of the Diaspora protocol with full support intended, and additional protocols after that.
+Python library to abstract social web federation protocols like Diaspora.
 
 ## Introduction
 
 The aim of Social-Federation is to provide and abstract multiple social web protocols like Diaspora in one package. This way applications can be built to (almost) transparently support many protocols without the app builder having to know everything about those protocols.
 
-## Usage and development
+While the library does aim to provide an easy way to implement protocols like Diaspora into your application, it will not be a one to one mirror image of said protocols. The idea is to present one unified collection of entities and high level methods to the application to use. Since protocols can support different feature sets or have different ideas on even simple entities like status messages, it would be impossible to model the core entities according to a single protocol.
 
-Please check [documentation](http://social-federation.readthedocs.io/en/latest/).
+![](http://social-federation.readthedocs.io/en/latest/_images/generic_diagram.png)
 
-## License
+## Status
 
-BSD 3-clause license (https://www.tldrlegal.com/l/bsd3).
+Currently the library supports a part of the Diaspora protocol with remaining parts being constantly added. See the [Diaspora](http://social-federation.readthedocs.io/en/latest/protocols.html#diaspora) protocol page for support status.
 
-## Author
+The code base is well tested and in use in several projects. Backward incompatible changes will however be made at this stage still, however those will be clearly documented in changelog entries.
+
+## Additional information
+
+### Installation and requirements
+
+See [installation documentation](http://social-federation.readthedocs.io/en/latest/install.html).
+
+### Usage and API documentation
+
+See [usage documentation](http://social-federation.readthedocs.io/en/latest/usage.html).
+
+### Support and help
+
+See [development and support documentation](http://social-federation.readthedocs.io/en/latest/development.html).
+
+### License
+
+[BSD 3-clause license](https://www.tldrlegal.com/l/bsd3)
+
+### Author
 
 Jason Robinson / https://jasonrobinson.me / https://github.com/jaywink

docs/example_projects.rst

@@ -0,0 +1,9 @@
+.. _example-projects:
+
+Projects using Social-Federation
+--------------------------------
+
+For examples on how to integrate this library into your project, check these examples:
+
+* `Socialhome <https://github.com/jaywink/socialhome>`_ - a federated home page builder slash personal social network server with high emphasis on card style content visualization.
+* `Social-Relay <https://github.com/jaywink/social-relay>`_ - a reference server for the public content relay system that uses the Diaspora protocol.

docs/index.rst

@@ -3,10 +3,10 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Social-Federation's documentation!
-=============================================
+Social-Federation
+=================
 
-Python library to abstract social federation protocols. Currently supports a subset of the Diaspora protocol with full support intended, and additional protocols after that.
+Python library to abstract social web federation protocols like Diaspora.
 
 Contents:
 
@@ -18,6 +18,7 @@ Contents:
    protocols
    usage
    development
+   example_projects
    changelog
 
 

docs/introduction.rst

@@ -3,19 +3,42 @@ Introduction
 
 The aim of Social-Federation is to provide and abstract multiple social web protocols like Diaspora in one package. This way applications can be built to (almost) transparently support many protocols without the app builder having to know everything about those protocols.
 
+While the library does aim to provide an easy way to implement protocols like Diaspora into your application, it will not be a one to one mirror image of said protocols. The idea is to present one unified collection of entities and high level methods to the application to use. Since protocols can support different feature sets or have different ideas on even simple entities like status messages, it would be impossible to model the core entities according to a single protocol.
+
+.. image:: _static/generic_diagram.png
+
 Status
 ------
 
-Currently the library supports a part of the Diaspora protocol with remaining parts being constantly added. See the :ref:`diaspora` protocol page for support status.
+Currently the library supports a part of the Diaspora protocol with remaining parts being constantly added. See the `Diaspora <http://social-federation.readthedocs.io/en/latest/protocols.html#diaspora>`_ protocol page for support status.
 
-The code base is well tested and in use in several projects. A lot of backward incompatible changes will however be made at this stage still, however those will be clearly documented in changelog entries.
+The code base is well tested and in use in several projects. Backward incompatible changes will however be made at this stage still, however those will be clearly documented in changelog entries.
 
-.. _example-projects:
+Additional information
+----------------------
 
-Projects using Social-Federation
---------------------------------
+Installation and requirements
+.............................
 
-For examples on how to integrate this library into your project, check these examples:
+See `installation documentation <http://social-federation.readthedocs.io/en/latest/install.html>`_.
+
+Usage and API documentation
+...........................
+
+See `usage documentation <http://social-federation.readthedocs.io/en/latest/usage.html>`_.
+
+Support and help
+................
+
+See `development and support documentation <http://social-federation.readthedocs.io/en/latest/development.html>`_.
+
+License
+.......
+
+`BSD 3-clause license <https://www.tldrlegal.com/l/bsd3>`_.
+
+Author
+......
+
+Jason Robinson / `jasonrobinson.me <https://jasonrobinson.me>`_ / `GitHub <https://github.com/jaywink>`_
 
-* `Socialhome <https://github.com/jaywink/socialhome>`_ - a federated home page builder slash personal social network server with high emphasis on card style content visualization.
-* `Social-Relay <https://github.com/jaywink/social-relay>`_ - a reference server for the public content relay system that uses the Diaspora protocol.

setup.py

@@ -1,17 +1,23 @@
 #!/usr/bin/env python
+import os
+
 from setuptools import setup, find_packages
 
 from federation import __version__
 
 
-description = 'Python library for abstracting social federation protocols'
+description = 'Python library to abstract social web federation protocols like Diaspora.'
+
+
+def get_long_description():
+    return open(os.path.join(os.path.dirname(__file__), "docs", "introduction.rst")).read()
 
 
 setup(
     name='Social-Federation',
     version=__version__,
     description=description,
-    long_description=description,
+    long_description=get_long_description(),
     author='Jason Robinson',
     author_email='mail@jasonrobinson.me',
     maintainer='Jason Robinson',