Commits

Martin von Löwis committed 5f9e822

Move documentation from README to sphinx.

  • Participants
  • Parent commits 07c5a36

Comments (0)

Files changed (2)

-Overview
---------
+This library helps writing OpenID applications (a.k.a relying
+parties). See the documentation_ for further usage information.
+Bug reports should be sent to the bugtracker_. The source code
+is maintained on bitbucket_.
 
-This is a library to implement OpenID 2.0 Relying Parties (RP). The RP
-itself will be a web application, and needs to implement all user
-interface, as well as to provide storage for certain persistent data.
-The assumption is that the web application has its own management of
-user accounts already, so OpenID will merely provide convenience for
-end users who wish to use their OpenID with the web application.
-
-The following three scenarios need to be considered:
-
-- an existing user logs in with an OpenID already known to the
-  application.
-
-- an existing user wants to add an OpenID to his account. The
-  recommended procedure is to let the user first log in regularly,
-  then claim the OpenID.
-
-- a new user logs in with a yet-unknown OpenID, and needs to be
-  registered.
-
-This library will implement the protocol between the application and
-the OpenID provider, as well as produce redirects to be sent to the
-user's browser, and process incoming redirects from the provider.
-
-The openid2rp module also includes a stand-alone server, as an example
-and a test.
-
-Programming Interface
----------------------
-
-The application can use the following API:
-
-normalize_uri(uri) -> kind, url
-
-  Returns either 'xri' or 'uri' as kind; XRIs are not further
-  supported. Applications should always normalize URIs claimed by the
-  end user, and perform identity comparisons on the normalized URIs
-  only.
-
-discover(url) -> (services, op_endpoint, op_local)
-
-  Perform OpenID discovery on the URL. Return the list of services
-  discovered (which should include either the signon or the server, in
-  either version 1.0 or 2.0), the provider endpoint to be used for
-  communication, and the provider-local identifier that the provider
-  will validate. Applications need to remember the claimed identifier,
-  and only identify the user by that string; the op_identifier is then
-  not further relevant to the application.
-
-associate(services, url) -> dict
-
-  Setup an association between the service and the provider. services
-  must be the list of services that was returned from discovery; url
-  is the provider endpoint URL. The resulting dictionary must be
-  preserved atleast until authentication is completed, and can be
-  reused at most until the 'expires_in' amount of seconds has passed.
-
-request_authentication(services, url, assoc_handle, return_to,
-                       claimed=None, op_local=None, realm=None) -> url
-
-  Create an authentication request; return the URL that the user
-  should be redirected to. services and url are the same parameters as
-  in associate; assoc_handle is the 'assoc_handle' field of the
-  association and return_to is the URL on which the application will
-  receive incoming provider redirects.  If the user had claimed an
-  identifier, this one and op_local from the discovery should be
-  passed. Passing the realm allows the RP to receive the same
-  identification information for multiple return_to URLs; for this to
-  work, the return_to URL must match the realm (see 9.2. of the OpenID
-  spec how matching is defined).
-
-authenticate(session, response) -> None
-
-  Process an authentication response.  session must be the established
-  session (minimally including assoc_handle and mac_key), response is
-  the query string as parsed by cgi.parse_qs.  If authentication
-  succeeds, return the list of signed fields.  If the user was not
-  authenticated, NotAuthenticated is raised.  If the HTTP request is
-  invalid (missing parameters, failure to validate signature),
-  different exceptions will be raised, typically ValueError.
-
-  Callers must check openid.response_nonce for replay attacks.
+.. _documentation: http://packages.python.org/openid2rp
+.. _bugtracker: http://bitbucket.org/loewis/openid2rp/issues
+.. _bitbucket: http://bitbucket.org/loewis/openid2rp

File doc/index.rst

-.. openid2rp documentation master file, created by
-   sphinx-quickstart on Wed Jun 30 22:02:35 2010.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+Welcome to openid2rp!
+=====================
 
-Welcome to openid2rp's documentation!
-=====================================
+.. module:: openid2rp
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
+This is a library to implement OpenID 2.0 Relying Parties (RP). The RP
+itself will be a web application, and needs to implement all user
+interface, as well as to provide storage for certain persistent data.
+The assumption is that the web application has its own management of
+user accounts already, so OpenID will merely provide convenience for
+end users who wish to use their OpenID with the web application.
+
+The following three scenarios need to be considered:
+
+- an existing user logs in with an OpenID already known to the
+  application.
+
+- an existing user wants to add an OpenID to his account. The
+  recommended procedure is to let the user first log in regularly,
+  then claim the OpenID.
+
+- a new user logs in with a yet-unknown OpenID, and needs to be
+  registered.
+
+This library will implement the protocol between the application and
+the OpenID provider, as well as produce redirects to be sent to the
+user's browser, and process incoming redirects from the provider.
+
+The openid2rp module also includes a stand-alone server, as an example
+and a test.
+
+Programming Interface
+---------------------
+
+The application can use the following API:
+
+.. function:: normalize_uri(uri) -> kind, url
+
+  Returns either 'xri' or 'uri' as kind; XRIs are not further
+  supported. Applications should always normalize URIs claimed by the
+  end user, and perform identity comparisons on the normalized URIs
+  only.
+
+.. function:: discover(url) -> (services, op_endpoint, op_local)
+
+  Perform OpenID discovery on the URL. Return the list of services
+  discovered (which should include either the signon or the server, in
+  either version 1.0 or 2.0), the provider endpoint to be used for
+  communication, and the provider-local identifier that the provider
+  will validate. Applications need to remember the claimed identifier,
+  and only identify the user by that string; the op_identifier is then
+  not further relevant to the application.
+
+.. function:: associate(services, url) -> dict
+
+  Setup an association between the service and the provider. services
+  must be the list of services that was returned from discovery; url
+  is the provider endpoint URL. The resulting dictionary must be
+  preserved atleast until authentication is completed, and can be
+  reused at most until the 'expires_in' amount of seconds has passed.
+
+.. function:: request_authentication(services, url, assoc_handle, return_to, claimed=None, op_local=None, realm=None) -> url
+
+  Create an authentication request; return the URL that the user
+  should be redirected to. services and url are the same parameters as
+  in associate; assoc_handle is the 'assoc_handle' field of the
+  association and return_to is the URL on which the application will
+  receive incoming provider redirects.  If the user had claimed an
+  identifier, this one and op_local from the discovery should be
+  passed. Passing the realm allows the RP to receive the same
+  identification information for multiple return_to URLs; for this to
+  work, the return_to URL must match the realm (see 9.2. of the OpenID
+  spec how matching is defined).
+
+.. function:: authenticate(session, response) -> None
+
+  Process an authentication response.  session must be the established
+  session (minimally including assoc_handle and mac_key), response is
+  the query string as parsed by cgi.parse_qs.  If authentication
+  succeeds, return the list of signed fields.  If the user was not
+  authenticated, NotAuthenticated is raised.  If the HTTP request is
+  invalid (missing parameters, failure to validate signature),
+  different exceptions will be raised, typically ValueError.
+
+  Callers must check openid.response_nonce for replay attacks.
+
+
 Indices and tables
 ==================