[Docs] move API docs from wiki to Sphinx

Author: stefankoegl

doc/_ext/jsonlexer.py

@@ -0,0 +1,14 @@
+def setup(app):
+    # enable Pygments json lexer
+    try:
+        import pygments
+        if pygments.__version__ >= '1.5':
+            # use JSON lexer included in recent versions of Pygments
+            from pygments.lexers import JsonLexer
+        else:
+            # use JSON lexer from pygments-json if installed
+            from pygson.json_lexer import JSONLexer as JsonLexer
+    except ImportError:
+        pass  # not fatal if we have old (or no) Pygments and no pygments-json
+    else:
+        app.add_lexer('json', JsonLexer())

doc/api/changes.rst

@@ -0,0 +1,87 @@
+API Changes
+===========
+
+This page lists changes to the Advanced API. The current version is 2.11. This versioning scheme has been introduced in [1].
+
+Version 2.11
+------------
+
+    added Download All subscriptions
+
+Version 2.10
+------------
+
+    added Authentication API [2]
+    added Device Synchronization API [3]
+    added Podcast Lists API [4]
+    added include_actions parameter to Device Update API [5]
+
+
+Version 2.9
+-----------
+
+    added XML format to some Simple API requests [6] [7]
+
+
+Version 2.8
+-----------
+
+    added JSONP as a format to Simple API requests [8]
+
+
+Version 2.7
+-----------
+
+    added API Parametrization
+
+
+Version 2.6
+-----------
+
+    added "released" to Retrieving Episode Data and Listing Favorite Episodes
+
+
+Version 2.5
+-----------
+    added "Subscribers Last Week" to Retrieving Podcast Data [9]
+
+
+Version 2.4
+-----------
+
+    added Saving a Setting [10]
+    added Retrieving Settings
+    added Listing Favorite Episodes
+
+
+Version 2.3
+-----------
+
+    added Retrieving Updates for a Device
+
+
+Version 2.2
+-----------
+
+    added Retrieving Top Tags
+    added Retrieving Podcasts of a Tag
+    added Retrieving Podcast Data
+    added Retrieving Episode Data
+
+
+Version 2.1
+-----------
+
+    added aggregated=true to Retrieving episode actions [11]
+
+
+Version 2.0
+-----------
+
+    added Add/remove subscriptions
+    added Retrieving subscription changes
+    added Uploading episode actions
+    added Retrieving episode actions
+    added (Re)naming devices and setting the type
+    added Getting a list of devices
+

doc/api/deprecation.rst

@@ -3,25 +3,35 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-API 3 Documentation (draft)
-===========================
+API Documentation
+=================
 
-*This site contains drafts for the gpodder.net's future API -- version 3 --
-which is not yet implemented.  The current API is documented at
-http://wiki.gpodder.org/wiki/Web_Services/API_2.*
+This is the specification of Version 2 of the public API for the gpodder.net
+Web Services.
 
-The gpodder.net API allows clients to interact with gpodder.net. The API is
-provided via a REST interface, and is free of charge within certain quotas, and
-completely free for open source clients (see :ref:`usage`).
+Please consult the :doc:`integration` before integrating the gpodder.net API
+in your application.
+
+There are two different APIs for different target audiences:
+
+* The **Simple API** targets developers who want to write quick integration
+  into their existing applications
+* The **Advanced API** targets developers who want tight integration into their
+  applications (with more features)
+
+The API is versioned so that changes in the major version number indicate
+backwards incompatible changes. All other changes preserve backwards
+compatibility. See :doc:`changes` for a list of changes. The current
+version is 2.11. This versioning scheme has been introduced in `bug 1273
+<https://bugs.gpodder.org/show_bug.cgi?id=1273>`_.
 
 Contents
 --------
 
 .. toctree::
    :maxdepth: 2
 
-   usage
    integration
    reference/index
-   deprecation
-   libraries
+   Libraries <http://wiki.gpodder.org/wiki/Web_Services/Libraries>
+   changes

doc/api/index.rst

@@ -68,16 +68,16 @@ device Id like the following
 * a web based player (*mywebservice-myusername*)
 
 When a previously unknown device Id is used in some API request, a device is
-automatically created. Refer to the :ref:`devices-api` on how to provide some
-information about the device. Users can manage their devices `online
+automatically created. Refer to the :doc:`reference/devices` on how to provide
+some information about the device. Users can manage their devices `online
 <https://gpodder.net/devices>`_.
 
 
 Podcast Directory
 ^^^^^^^^^^^^^^^^^
 
 The most basic *passive* integration with gpodder.net is to access some of its
-public data. Refer to the :ref:`directory-api` for available endpoints.
+public data. Refer to the :doc:`reference/directory` for available endpoints.
 
 
 Subscription Management
@@ -86,7 +86,7 @@ Subscription Management
 The most common form of *active* integration is subscription management.
 Clients can upload the podcast subscriptions using their device Id and receive
 subscription changes (for their device) that were made online. Refer to the
-:ref:`subscriptions-api` for additional information.
+:doc:`reference/subscriptions` for additional information.
 
 
 Episode Actions Synchronization
@@ -95,5 +95,5 @@ Episode Actions Synchronization
 Clients can upload and download certain actions (episode downloaded, played,
 deleted) to/from gpodder.net. This gives the user a central overview of
 where and when he accessed certain podcast episodes, and allows clients to
-synchronise states between applications. Refer to the :ref:`events-api` for
-further information.
+synchronise states between applications. Refer to the :doc:`reference/events`
+for further information.

doc/api/integration.rst

@@ -1,2 +1,36 @@
 Authentication API
 ==================
+
+Login / Verify Login
+--------------------
+
+..  http:post:: /api/2/auth/(username)/login.json
+    :synopsis: verify the login status
+
+    * since 2.10
+
+    Log in the given user for the given device via HTTP Basic Auth.
+
+    :param username: the username which should be logged in
+    :status 401: If the URL is accessed without login credentials provided
+    :status 400: If the client provides a cookie, but for a different username than the one given
+    :status 200: the response headers have a ``sessionid`` cookie set.
+
+    The client can use this URL with the cookie in the request header to check
+    if the cookie is still valid.
+
+
+Logout
+------
+
+..  http:post:: /api/2/auth/(username)/logout.json
+    :synopsis: logout
+
+    * since 2.10
+
+    Log out the given user. Removes the session ID from the database.
+
+    :param username: the username which should be logged out
+    :status 200: if the client didn't send a cookie, or the user was
+                 successfully logged out
+    :status 400: if the client provides a cookie, but for a different username than the one given

doc/api/libraries.rst

@@ -0,0 +1,34 @@
+Client Parametrization
+======================
+
+The client configuration file is located at
+http://gpodder.net/clientconfig.json and contains information that clients
+should retrieve before making requests to the APIs.
+
+If a client cannot retrieve and process this file (either temporarily or
+permanently), it can assume the default values provided below. However,
+the URLs in the file might reflect changed URLs and/or mirror servers. If a
+client decides to permanently ignore this file, it might hit an outdated URL
+or an overloaded server.
+
+
+Commented Example
+-----------------
+
+.. code-block:: json
+
+    {
+        "mygpo":  {
+            "baseurl": "http://gpodder.net/"
+        }
+
+        "mygpo-feedservice": {
+            "baseurl": "http://mygpo-feedservice.appspot.com/"
+        }
+
+        "update_timeout": 604800,
+    }
+
+* ``mygpo/baseurl``: URL to which the gpodder.net API Endpoints should be appended
+* ``mygpo-feedservice/baseurl``: Base URL of the gpodder.net feed service
+* ``update_timeout``: Time in seconds for which the values in this file can be considered valid.