doc: Fix #910 by referencing External Services

doc/ref/modules/mod_facebook.rst

@@ -1,25 +1,24 @@
 .. highlight:: django
 .. include:: meta-mod_facebook.rst
 
-Plugs into the authentication / signup system to enable Facebook
-login.
+The mod_facebook module plugs into the
+:ref:`authentication systen <guide-authentication>` to enable `Facebook login`_
+on your site.
 
-Module is still largely undocumented, but this is what was said on the
-mailing list about it:
+Configuration
+-------------
 
-The url of your site needs to be correctly configured in the Facebook app configuration at Facebook for your site to work.
+:ref:`Activate <activating-modules>` mod_facebook, then head to ‘Auth’ >
+‘External services’ in the admin interface to enter your Facebook app ID and
+secret. Enable Facebook login by checking the ‘Use Facebook authentication’ box.
+This will add a ‘Log in with Facebook’ button to the logon form on your site.
 
-The current (hard coded) test site has the url http://127.0.0.1:8000/ configured.
-Use the config keys:
+If you need extended permissions, add them to the ‘Scope’ textbox. Note that the
+module needs the ‘email’ permission for login to work.
 
-- ``mod_facebook.appid``
-- ``mod_facebook.appsecret``
-
-Both values you can find when you register your site (as an application) at Facebook.
-
-If you need extended permission for the acquired token, you can use
-the ``mod_facebook.scope`` configuration key to set the scope. Note
-that the module always will need the "email" permission for the login
-to work.
+.. seealso::
 
-.. todo:: Unfinished doc
+    * :ref:`mod_instagram`
+    * :ref:`mod_twitter`
+
+.. _Facebook login: https://developers.facebook.com/docs/facebook-login/

doc/ref/modules/mod_instagram.rst

@@ -2,3 +2,8 @@
 .. include:: meta-mod_instagram.rst
 
 .. todo:: Not yet documented.
+
+.. seealso::
+
+    * :ref:`mod_facebook`
+    * :ref:`mod_twitter`

doc/ref/modules/mod_twitter.rst

@@ -9,45 +9,45 @@ which has a continuous HTTP connection to the Twitter Streaming
 API. This way, Tweets arrive instantly at your Zotonic site, no
 polling necessary!
 
-Installation
-------------
-
-Enable the mod_twitter module. Then
-
-In the "config" section in the admin, create 2 new config keys:
-
-``mod_twitter`` / ``api_login`` - Your Twitter username
-
-``mod_twitter`` / ``api_password`` - Your Twitter password
-
-We need your account details to startup the streaming API. mod_twitter
-will never write to your account: it only reads your updates.
-
-Now, activate the Twitter module under "Modules".
-
-When you have activated the Twitter module, you should go to a
-person's page in the admin. In the edit page, you see in the sidebar a
-new item, called "Twitter ID". Here you can enter the numeric Twitter
-ID of this user. Visit `My Twitter Id <http://www.mytwitterid.com/>`_
-to find out your twitter ID.
-
-At this point the module will login to Twitter and start following the
-user(s) that you entered their Twitter IDs for. Only `public (or unprotected)`_
+Twitter login
+-------------
+
+First, create an app on Twitter. Point it’s callback URL to your Zotonic site.
+Then in your site, :ref:`activate <activating-modules>` mod_twitter. Head to
+‘Auth’ > ‘External services’ in the admin interface to enter your Twitter app’s
+consumer key and secret. Enable Twitter login by checking the ‘Use Twitter
+authentication’ box. This will add a ‘Log in with Twitter’ button to the logon
+form on your site.
+
+Importing Tweets
+----------------
+
+The mod_twitter module can import Tweets into Zotonic using Twitter’s
+`Streaming API`_.
+
+:ref:`Activate <activating-modules>` mod_twitter. Then head
+to ‘Auth’ > ‘External services’ in the admin interface to enter your Twitter
+access token and secret.
+
+The module will follow any user(s) in your site that you entered their Twitter
+ID for. You can so by going to a person’s page in the admin. In the edit
+page’s right sidebar, you will find a new item, ‘Twitter ID’. Here, enter the
+`numeric Twitter ID`_ of the user. Only `public (or unprotected)`_
 Tweets will be imported.
 
 Domain model
-------------
+^^^^^^^^^^^^
 
 The :term:`domain model` for this module is the following: the module
-creates a :ref:`category <guide-datamodel-categories>` `Tweet` as a
-subcategory of `text.` Each time a Tweet is imported, a resource of
+creates a :ref:`category <guide-datamodel-categories>` ‘Tweet’ as a
+subcategory of ‘text’. Each time a Tweet is imported, a resource of
 this category is created.
 
-From the Tweet there is an `author` edge to the person that created
+From the Tweet there is an ‘author’ edge to the person that created
 the Tweet (i.e. the user who you set the Twitter ID on).
 
 The body text of the Tweet resource is HTML will already be
-preprocessed with the :ref:`filter-twitter` filter, so URLs, hash-tags
+preprocessed with the :ref:`filter-twitter` filter, so URLs, hashtags
 and @-links are converted to HTML already when the Tweet is saved.
 
 The original value of the Tweet (the JSON object received from Twitter)
@@ -56,15 +56,11 @@ displayed like this::
 
     {% print m.rsc[id].tweet %}
 
-Using logon with Twitter
-------------------------
-
-Add an app on Twitter and get the consumer key / secret. In Zotonic,
-configure two config keys, ``mod_twitter.consumer_key`` and
-``mod_twitter.consumer_secret`` to contain these values. Now set up
-the callback URL to your Zotonic site in the Twitter app. The logon
-window will now automatically show a "Sign in with Twitter" button.
+.. seealso::
 
-.. seealso:: :ref:`filter-twitter` filter
+    * :ref:`mod_facebook`
+    * :ref:`mod_instagram`
 
 .. _public (or unprotected): https://support.twitter.com/articles/20169886
+.. _Streaming API: https://dev.twitter.com/streaming/overview
+.. _numeric Twitter ID: http://www.mytwitterid.com