adjusted style, added examples

api_template/CNAuthorization.py

@@ -2,9 +2,8 @@
 import Types
 
 
-
-def setRightsHolder(session,id,userId,serialVersion):
-  """
+def setRightsHolder(session, id, userId, serialVersion):
+    """
   ``PUT /owner/{id}`` |br| Changes ownership (RightsHolder) of the specified object to the :term:`subject` specified by `userId`
 
   v2.0: The supplied identifier may be a :term:`PID` or a :term:`SID`.
@@ -17,9 +16,10 @@ def setRightsHolder(session,id,userId,serialVersion):
 
   Parameters:
     session (Types.Session): |session| 
-    id (Types.Identifier): Identifier of the object to be modified. May be either a PID or a SID, the latter acting on the HEAD PID. Transmitted as part of the URL path and must be escaped accordingly.
-    userId (Types.Subject): The subject that will be taking ownership of the specified object.  Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message.
-    serialVersion (unsigned long): The serialVersion of the system metadata that is the intended target for the change. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message.
+    id (Types.Identifier): Identifier of the object to be modified. May be either a PID or a SID, the latter acting on
+      the HEAD PID. Transmitted as part of the URL path and must be escaped accordingly.
+    userId (Types.Subject): The subject that will be taking ownership of the specified object. |stringparam|
+    serialVersion (unsigned long): The serialVersion of the system metadata that is the intended target for the change. |stringparam|
 
   Returns:
     Types.Identifier: Identifier of the object that was modified
@@ -36,19 +36,19 @@ def setRightsHolder(session,id,userId,serialVersion):
   .. include:: /apis/examples/cnauthorization_setrightsholder.txt
 
   """
-  return None
+    return None
 
 
-
-def isAuthorized(session,id,action):
-  """
+def isAuthorized(session, id, action):
+    """
   ``GET /isAuthorized/{id}?action={action}`` |br| Test if the user identified by the provided token has authorization for operation on the specified object.
 
   A successful operation is indicated by a return HTTP status of 200.
 
   Failure is indicated by an exception such as :exc:`NotAuthorized` being returned.
 
-  A successful response is indicated by a response HTTP status of 200. The body of the response is arbitrary and SHOULD be ignored by the caller.
+  A successful response is indicated by a response HTTP status of 200. The body of the response is arbitrary and SHOULD
+  be ignored by the caller.
 
   If the action is not authorized, then a :exc:`NotAuthorized` exception MUST be raised.
 
@@ -62,8 +62,9 @@ def isAuthorized(session,id,action):
 
   Parameters:
     session (Types.Session): |session| 
-    id (Types.Identifier): The identifer of the resource for which access is being checked. May be either a PID or a SID, the latter returning results as if called with the HEAD PID. Transmitted as part of the URL path and must be escaped accordingly.
-    action (Types.Permission): The type of operation which is being requested for the given identifier. Transmitted as a URL query parameter, and so must be escaped accordingly.
+    id (Types.Identifier): The identifer of the resource for which access is being checked. May be either a PID or a
+      SID, the latter returning results as if called with the HEAD PID. Transmitted as part of the URL path and must be escaped accordingly.
+    action (Types.Permission): The type of operation which is being requested for the given identifier. |urlparam|
 
   Returns:
     boolean: True if the operation is allowed
@@ -72,19 +73,19 @@ def isAuthorized(session,id,action):
     Exceptions.ServiceFailure:  (errorCode=500, detailCode=1760)
     Exceptions.InvalidToken:  (errorCode=401, detailCode=1840)
     Exceptions.NotFound:  (errorCode=404, detailCode=1800)
-    Exceptions.NotAuthorized: This error is raised if the request comes from a black listed source (e.g. a temporary block may be imposed on a source that calls this method too many times within some time interval) (errorCode=401, detailCode=1820)
+    Exceptions.NotAuthorized: This error is raised if the request comes from a black listed source (e.g. a temporary
+      block may be imposed on a source that calls this method too many times within some time interval) (errorCode=401, detailCode=1820)
     Exceptions.NotImplemented:  (errorCode=501, detailCode=1780)
     Exceptions.InvalidRequest:  (errorCode=400, detailCode=1761)
 
   .. include:: /apis/examples/cnauthorization_isauthorized.txt
 
   """
-  return None
+    return None
 
 
-
-def setAccessPolicy(session,id,accessPolicy,serialVersion):
-  """
+def setAccessPolicy(session, id, accessPolicy, serialVersion):
+    """
   ``PUT /accessRules/{id}`` |br| Sets the access permissions for an object identified by *id*.
 
   Triggers a change to the system metadata modified time stamp.
@@ -103,9 +104,10 @@ def setAccessPolicy(session,id,accessPolicy,serialVersion):
 
   Parameters:
     session (Types.Session): |session| 
-    id (Types.Identifier): The object for which access control is being updated. May be either a PID or a SID, the latter acting on the HEAD PID only. Transmitted as part of the URL path and must be escaped accordingly.
-    accessPolicy (Types.AccessPolicy): The desired privileges to be assigned to the object. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message.
-    serialVersion (unsigned long): The serialVersion of the system metadata that is the intended target for the change. Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message.
+    id (Types.Identifier): The object for which access control is being updated. May be either a PID or a SID, the
+      latter acting on the HEAD PID only. |urlparam|
+    accessPolicy (Types.AccessPolicy): The desired privileges to be assigned to the object. |xmlparam|
+    serialVersion (unsigned long): The serialVersion of the system metadata that is the intended target for the change. |stringparam|
 
   Returns:
     boolean: True if the operation succeeds, otherwise false.
@@ -122,5 +124,4 @@ def setAccessPolicy(session,id,accessPolicy,serialVersion):
   .. include:: /apis/examples/cnauthorization_setaccesspolicy.txt
 
   """
-  return None
-
+    return None

api_template/CNDiagnostic.py

@@ -5,7 +5,9 @@
 
 def echoCredentials(session):
   """
-  ``GET /diag/subject`` |br| Echo the credentials used to make the call. This method can be used to verify the client certificate is valid and contains the expected information.
+  ``GET /diag/subject`` |br| Echo the credentials used to make the call.
+
+  This method can be used to verify the client certificate is valid and contains the expected information.
 
   v2.0: This method was added to the Version 2.0 API.
 
@@ -14,7 +16,7 @@ def echoCredentials(session):
   :REST URL: ``GET /diag/subject``
 
   Parameters:
-    session (Types.Session): |session| 
+    session (Types.Session): |session|
 
   Returns:
     Types.SubjectInfo: The subjects and groups parsed from the supplied session information.
@@ -33,9 +35,10 @@ def echoCredentials(session):
 
 def echoSystemMetadata(session,sysmeta):
   """
-  ``POST /diag/sysmeta`` |br| Parse and echo the provided system metadata
+  ``POST /diag/sysmeta`` |br| Parse and echo the provided system metadata.
 
-  On successful parsing, a copy of the system metadata is returned, otherwise an exception is returned indicating an error condition.
+  On successful parsing, a copy of the system metadata is returned, otherwise an
+  exception is returned indicating an error condition.
 
   v2.0: This operation is new to version 2.0.
 
@@ -44,7 +47,7 @@ def echoSystemMetadata(session,sysmeta):
   :REST URL: ``POST /diag/sysmeta``
 
   Parameters:
-    session (Types.Session): |session| 
+    session (Types.Session): |session|
     sysmeta (Types.SystemMetadata): A SystemMetadata object to be examined. The object is parsed and error conditions reported by an exception response. On successful parsing, the SystemMetadata object is echoed back with a HTTP 200 status. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message.
 
   Returns:
@@ -68,11 +71,16 @@ def echoSystemMetadata(session,sysmeta):
 
 def echoIndexedObject(session,queryEngine,sysmeta,object):
   """
-  ``POST /diag/object`` |br| Parse and echo the provided science metadata or resource map document. The response is governed by the type of object provided in the request, and on success is one or more documents that are the result of parsing for indexing.
+  ``POST /diag/object`` |br| Parse and echo the provided science metadata or resource map document.
+
+  The response is governed by the type of object provided in the request, and on
+  success is one or more documents that are the result of parsing for indexing.
 
-  Since DataONE supports multiple types of query engine, the query engine to be used for parsing is specified in the request.
+  Since DataONE supports multiple types of query engine, the query engine to be
+  used for parsing is specified in the request.
 
-  The servce may terminate the POST operation if the size of the object is beyond a reasonable size.
+  The servce may terminate the POST operation if the size of the object is
+  beyond a reasonable size.
 
   v2.0: This operation is new to version 2.0.
 
@@ -81,10 +89,10 @@ def echoIndexedObject(session,queryEngine,sysmeta,object):
   :REST URL: ``POST /diag/object``
 
   Parameters:
-    session (Types.Session): |session| 
+    session (Types.Session): |session|
     queryEngine (string): A valid query engine name as reported by :func:`listQueryEngines` Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message.
     sysmeta (Types.SystemMetadata): A SystemMetadata object that passes the echoSystemMetadata diagnostic. Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message.
-    object (bytes): A document (e.g. science metadata or resource map) that is to be evalauted for indexing. 
+    object (bytes): A document (e.g. science metadata or resource map) that is to be evalauted for indexing.
 
   Returns:
     Types.OctetStream: A document representing the parsed object as it would be prior to being added to a search index. For the solr query engine for example, this would be the equivalent of a *<add><doc> .. </doc> .. </add>* structure with possibly multiple documents.
@@ -104,4 +112,3 @@ def echoIndexedObject(session,queryEngine,sysmeta,object):
 
   """
   return None
-

requirements.txt

@@ -1,3 +1,4 @@
 recommonmark
 plantweb
 git+https://github.com/datadavev/docutils_sqltable#egg=sqltable
+

source/_static/custom.css

@@ -10,12 +10,12 @@ dl.function > dt:target, dl.exception > dt:target {
 }
 
 /* for REST URL after method description */
-dl.function > dd > p > code:first-of-type {
+/*dl.function > dd > p > code:first-of-type {
   background-color: inherit;
   display: block;
   margin-top: 1rem;
 }
-
+*/
 /* the br in the first para of a function description */
 dl.function > dd > p > br:first-of-type {
 }

source/apis/api_substitutions.txt

@@ -18,3 +18,8 @@
 
 .. |extrace| replace:: Optional set of key-value pairs that can include the name of the method that raised the error plus other details such as parameters used in the call that can be helpful for debugging. Sensitive information such as passwords must **never** be logged or recorded in error messages.
 
+.. |stringparam| replace:: Transmitted as a UTF-8 String as a *Param part* of the MIME multipart/mixed message.
+
+.. |urlparam| replace:: Transmitted as a URL query parameter, and so must be escaped accordingly.
+
+.. |xmlparam| replace:: Transmitted as an UTF-8 encoded XML structure for the respective type as defined in the DataONE types schema, as a *File part* of the MIME multipart/mixed message.

source/apis/examples/cndiagnostic_echocredentials.txt

@@ -1,4 +1,25 @@
 **Example**
 
-.. TODO:: Example for CNDiagnostic.echoCredentials
+Echo credentials in the certificate ``usercred.pem``:
 
+.. code-block:: xml
+
+  curl -s --cert usercred.pem https://cn.dataone.org/cn/v2/diag/subject | xml fo
+
+  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+  <ns2:subjectInfo xmlns:ns2="http://ns.dataone.org/service/types/v1">
+  <person>
+    <subject>CN=Dave Vieglais A335,O=Google,C=US,DC=cilogon,DC=org</subject>
+    <givenName>Dave</givenName>
+    <familyName>Vieglais</familyName>
+    <equivalentIdentity>CN=David Vieglais A2105,O=University of Kansas,C=US,DC=cilogon,DC=org</equivalentIdentity>
+    <verified>true</verified>
+  </person>
+  <person>
+    <subject>CN=David Vieglais A2105,O=University of Kansas,C=US,DC=cilogon,DC=org</subject>
+    <givenName>Dave</givenName>
+    <familyName>Vieglais</familyName>
+    <equivalentIdentity>CN=Dave Vieglais A335,O=Google,C=US,DC=cilogon,DC=org</equivalentIdentity>
+    <verified>false</verified>
+  </person>
+  </ns2:subjectInfo>