Sync spec tooling with telepathy

We now have minimal differences with the upstream tooling (just index.html and style.css).
author: Alex Merry <dev@randomguy3.me.uk> 2010-12-23 13:00:40 +0000
committer: Alex Merry <dev@randomguy3.me.uk> 2010-12-23 13:00:40 +0000
commit: 02b45059914886d9dddb67bda597a646c7748dc8 (patch)
tree: a1c43f6126f9a38b95c620ed5953f0aa6b2acfec
parent: aee1bb29d20780726dc18a314bae2403e484a566 (diff)
9 files changed, 413 insertions, 7 deletions
diff --git a/doc/templates/devhelp.devhelp2 b/doc/templates/devhelp.devhelp2
index 798a8c2..cd7fe7a 100644
--- a/doc/templates/devhelp.devhelp2
+++ b/doc/templates/devhelp.devhelp2
@@ -4,13 +4,19 @@
 #for $interface in $spec.interfaces
   <sub name="$interface.name" link="$interface.get_url()"/>
 #end for
+#if len($spec.generic_types) > 0
+  <sub name="Generic Types" link="generic-types.html"/>
+#end if
+#if len($spec.errors) > 0
+  <sub name="Errors" link="errors.html"/>
+#end if
   <sub name="Full Index" link="fullindex.html"/>
  </chapters>
  <functions>
 #for $obj in $spec.everything.values() + $spec.types.values() + $spec.errors.values()
 #for $entry in $obj.get_index_entries()
   <keyword type="$obj.devhelp_name" name="$entry" link="$obj.get_url()" #slurp
-#if $obj.deprecated: deprecated="true" #slurp
+#if $obj.is_deprecated: deprecated="true" #slurp
 />
 #end for
 #end for
diff --git a/doc/templates/errors.html b/doc/templates/errors.html
new file mode 100644
index 0000000..4e231a7
--- /dev/null
+++ b/doc/templates/errors.html
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd" "">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+ <head>
+  <title>Errors</title>
+  <link rel="stylesheet" href="style.css" type="text/css"/>
+ </head>
+ <body>
+  <div class="header">
+  <h1>Errors</h1>
+   <a href="index.html">Interface Index</a>
+   (<a href="interfaces.html">Compact</a>)
+   | <a href="#summary">Summary</a>
+   | <a href="#errors">Errors</a>
+  </div>
+  <div class="main">
+   <div class="summary">
+    <a name="summary"></a>
+    <h3>Errors</h3>
+    <table class="summary">
+     #for $error in $spec.sorted_errors
+      #if $error.is_deprecated
+       <tr class="deprecated">
+      #else
+       <tr>
+      #end if
+       <td><a href="$error.get_url()">$error.short_name</a></td>
+       <td>
+        #if $error.is_deprecated: (deprecated)
+       </td>
+      </tr>
+     #end for
+    </table>
+   </div>
+
+   #if $spec.errors_section
+    $spec.errors_section.get_docstring()
+   #end if
+
+   <div class="outset errors error">
+    <a name="errors"></a>
+    <h1>Errors</h1>
+    #for $error in $spec.sorted_errors
+     <div class="inset error">
+      <a name="$error.get_anchor()"></a>
+      <span class="permalink">(<a href="$error.get_url()">Permalink</a>)</span>
+      <h2>
+       $error.short_name
+      </h2>
+
+      <div class="indent">
+        <code>$error.name</code>
+      </div>
+
+      $error.get_added()
+      $error.get_deprecated()
+      $error.get_docstring()
+     </div>
+    #end for
+   </div>
+   </div>
+
+ </body>
+</html>
diff --git a/doc/templates/fullindex.html b/doc/templates/fullindex.html
index 7ad3153..a78116b 100644
--- a/doc/templates/fullindex.html
+++ b/doc/templates/fullindex.html
@@ -37,14 +37,14 @@
    #for l, g in $groups
     <tr><th colspan="3"><a name="$l"></a>$l</th></tr>
     #for $n in $g
-     #if $n[1].deprecated
+     #if $n[1].is_deprecated
       <tr class="deprecated">
      #else
       <tr>
      #end if
       <td>
        <a href="$n[1].get_url()" title="$n[1].get_title()">$n[0]</a>
-       #if $n[1].deprecated: (deprecated)
+       #if $n[1].is_deprecated: (deprecated)
       </td>
       <td>$n[1].get_type_name()</td>
       <td>
diff --git a/doc/templates/generic-types.html b/doc/templates/generic-types.html
new file mode 100644
index 0000000..87f72f7
--- /dev/null
+++ b/doc/templates/generic-types.html
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd" "">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+ <head>
+  <title>Generic Types</title>
+  <link rel="stylesheet" href="style.css" type="text/css"/>
+ </head>
+ <body>
+  <div class="header">
+  <h1>Generic Types</h1>
+   <a href="index.html">Interface Index</a>
+   (<a href="interfaces.html">Compact</a>)
+   | <a href="#summary">Summary</a>
+   | <a href="#types">Types</a>
+  </div>
+  <div class="main">
+    <div class="summary">
+     <a name="summary"></a>
+     <h3>Generic Types</h3>
+     <table class="summary">
+      #for $type in $spec.generic_types
+       #if $type.is_deprecated
+        <tr class="deprecated">
+       #else
+        <tr>
+       #end if
+       <td><a href="$type.get_url()">$type.short_name</a></td>
+       <td>$type.get_type_name()</td>
+       <td>$type.dbus_type</td>
+       <td>
+        #if $type.is_deprecated: (deprecated)
+       </td>
+      </tr>
+      #end for
+     </table>
+    </div>
+
+   <div class="outset types type">
+    <a name="types"></a>
+    <h1>Generic Types</h1>
+    #for $type in $spec.generic_types
+     <div class="inset type">
+      <a name="$type.get_anchor()"></a>
+      <span class="permalink">$type.get_type_name() (<a href="$type.get_url()">Permalink</a>)</span>
+      <h2>
+       $type.short_name &mdash; $type.dbus_type
+      </h2>
+
+      $type.get_added()
+      $type.get_deprecated()
+      $type.get_docstring()
+      $type.get_breakdown()
+     </div>
+    #end for
+   </div>
+   </div>
+
+ </body>
+</html>
diff --git a/doc/templates/index.html b/doc/templates/index.html
index a749f6f..6b9b62f 100644
--- a/doc/templates/index.html
+++ b/doc/templates/index.html
@@ -10,6 +10,12 @@
    <h1>$spec.title</h1>
    <a href="#Interfaces">Interfaces</a>
    (<a href="interfaces.html">Compact</a>)
+#if len($spec.generic_types) > 0
+   | <a href="generic-types.html">Generic Types</a>
+#end if
+#if len($spec.errors) > 0
+   | <a href="errors.html">Errors</a>
+#end if
    | <a href="fullindex.html">Full Index</a>
   </div>
 
@@ -60,7 +66,7 @@
      #end if
      #if $item.causes_havoc
       <li class="causes-havoc">
-     #elif $item.deprecated
+     #elif $item.is_deprecated
       <li class="deprecated">
      #else
       <li>
@@ -68,7 +74,7 @@
       <a href="$item.get_url()">$item.name</a>
       #if $item.causes_havoc
        (unstable)
-      #elif $item.deprecated
+      #elif $item.is_deprecated
        (deprecated)
       #end if
      </li>
@@ -80,6 +86,19 @@
   #end def
   $output($spec.items, False)
 
+#if len($spec.generic_types) > 0 or len($spec.errors) > 0
+  <a name="other"></a>
+  <h3>Other</h3>
+  <ul>
+  #if len($spec.generic_types) > 0
+   <li><a href="generic-types.html">Generic Types</a></li>
+  #end if
+  #if len($spec.errors) > 0
+   <li><a href="errors.html">Errors</a></li>
+  #end if
+  </ul>
+#end if
+
   </div>
  </body>
 </html>
diff --git a/doc/templates/interface.html b/doc/templates/interface.html
index 9e0bb7f..feac841 100644
--- a/doc/templates/interface.html
+++ b/doc/templates/interface.html
@@ -13,10 +13,14 @@
    <a href="index.html">Interface Index</a>
    (<a href="interfaces.html">Compact</a>)
    | <a href="#summary">Summary</a>
+   #if $interface.client_interests: | <a href="#client-interests">Client Interests</a>
    #if $interface.docstring: | <a href="#description">Description</a>
    #if $interface.methods: | <a href="#methods">Methods</a>
    #if $interface.signals: | <a href="#signals">Signals</a>
    #if $interface.properties: | <a href="#properties">Properties</a>
+   #if $interface.tpproperties: | <a href="#tpproperties">Telepathy Properties</a>
+   #if $interface.contact_attributes: | <a href="#contact-attributes">Contact Attributes</a>
+   #if $interface.handler_capability_tokens: | <a href="#handler-capability-tokens">Handler Capability Tokens</a>
    #if $interface.types: | <a href="#types">Types</a>
   </div>
   <div class="main">
@@ -24,6 +28,14 @@
     #if $interface.methods or $interface.signals or $interface.properties or $interface.types or $interface.tpproperties
     <div class="summary">
      <a name="summary"></a>
+     #if $interface.client_interests
+     <h3>Client Interests</h3>
+     <table class="summary">
+      #for $interest in $interface.client_interests
+      <td><a href="$interest.get_url()">$interest.name</a></td>
+      #end for
+     </table>
+     #end if
      #if $interface.methods
      <h3>Methods</h3>
      <table class="summary">
@@ -88,6 +100,52 @@
     </table>
     #end if
 
+     #if $interface.tpproperties
+     <h3>Telepathy Properties</h3>
+     <table class="summary">
+      #for $property in $interface.tpproperties
+       <tr class="deprecated">
+       <td><a href="$property.get_url()">$property.short_name</a></td>
+       <td>
+        $property.dbus_type
+        #if $property.type: (<a href="$property.get_type_url()" title="$property.get_type_title()">$property.get_type().short_name</a>)
+       </td>
+      </tr>
+      #end for
+    </table>
+    #end if
+
+     #if $interface.contact_attributes
+     <h3>Contact Attributes</h3>
+     <table class="summary">
+      #for $token in $interface.contact_attributes
+       <tr class="contact-attribute">
+       <td><a href="$token.get_url()">$token.name</a></td>
+       <td>
+        $token.dbus_type
+        #if $token.type: (<a href="$token.get_type_url()" title="$token.get_type_title()">$token.get_type().short_name</a>)
+       </td>
+      </tr>
+      #end for
+    </table>
+    #end if
+
+     #if $interface.handler_capability_tokens
+     <h3>Handler Capability Tokens</h3>
+     <table class="summary">
+      #for $token in $interface.handler_capability_tokens
+       <tr class="handler-capability-token">
+         <td><a href="$token.get_url()">$token.name</a>
+           #if $token.is_family
+             (etc.)
+           #end if
+         </td>
+       <td>
+       </td>
+      </tr>
+      #end for
+    </table>
+    #end if
 
      #if $interface.types
      <h3>Types</h3>
@@ -145,6 +203,27 @@
     $interface.get_docstring()
    #end if
 
+   #if $interface.client_interests
+   <div class="outset client-interests client-interest">
+    <a name="client-interests"></a>
+    <h1>Client Interests</h1>
+    <div>
+     Set using the
+     <a href="Connection.html#org.freedesktop.Telepathy.Connection.AddClientInterest">AddClientInterest</a> and
+     <a href="Connection.html#org.freedesktop.Telepathy.Connection.RemoveClientInterest">RemoveClientInterest</a> methods.
+    </div>
+    #for $interest in $interface.client_interests
+    <div class="inset client-interest">
+     <a name="$interest.get_anchor()"></a>
+     <span class="permalink">(<a href="$interest.get_url()">Permalink</a>)</span>
+     <h2>$interest.name</h2>
+
+     $interest.get_docstring()
+    </div>
+    #end for
+   </div>
+   #end if
+
    #if $interface.methods
    <div class="outset methods method">
     <a name="methods"></a>
@@ -278,6 +357,62 @@
      </h2>
       <div class="access">$property.get_access()</div>
 
+     #if $property.sometimes_immutable:
+     <div class="annotation immutable">Depending on the protocol, this
+       property may be <strong>immutable</strong> which means that it can never
+       #if $interface.is_channel_related:
+       change once the channel has been created. Immutable properties SHOULD
+       appear in the channel detail list
+       of <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.NewChannels">NewChannels</a>
+       signals.
+       #else
+       change.
+       #end if
+     </div>
+     #elif $property.immutable:
+     <div class="annotation immutable">This property is
+       <strong>immutable</strong> which means that it can never
+       #if $interface.is_channel_related:
+       change once the channel has been created. Immutable properties SHOULD
+       appear in the channel detail list
+       of <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.NewChannels">NewChannels</a>
+       signals.
+       #else
+       change.
+       #end if
+     </div>
+     #end if
+
+     #if $property.sometimes_requestable:
+     <div class="annotation requestable">Depending on the protocol, this
+       property may be <strong>requestable</strong>, which means that it may be
+       allowed in the properties hash of a channel request such as in the
+       <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.CreateChannel">CreateChannel</a>
+       and
+       <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.EnsureChannel">EnsureChannel</a>
+       methods
+       on <a href="Connection_Interface_Requests.html">Requests</a>
+       and <a href="Channel_Dispatcher.html">ChannelDispatcher</a>.
+       If supported on this protocol, the property should appear in either the
+       Fixed_Properties or Allowed_Properties of
+       a <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.RequestableChannelClasses">RequestableChannelClass</a>
+       advertised by the CM.</div>
+     #elif $property.requestable:
+     <div class="annotation requestable">This property
+       is <strong>requestable</strong>, which means that it is allowed
+       in the properties hash of a channel request such as in the
+       <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.CreateChannel">CreateChannel</a>
+       and 
+       <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.EnsureChannel">EnsureChannel</a>
+       methods
+       on <a href="Connection_Interface_Requests.html">Requests</a>
+       and <a href="Channel_Dispatcher.html">ChannelDispatcher</a>.
+       The property should also appear in either the Fixed_Properties
+       or Allowed_Properties of
+       a <a href="Connection_Interface_Requests.html#org.freedesktop.Telepathy.Connection.Interface.Requests.RequestableChannelClasses">RequestableChannelClass</a>
+       advertised by the CM.</div>
+     #end if
+
      $property.get_added()
      $property.get_changed()
      $property.get_deprecated()
@@ -301,12 +436,104 @@
      </div>
      #end if
 
+      #if $property.is_connection_parameter:
+      <div class="annotation connection-parameter">
+        <p><span class='note'>Note:</span> Connections implementing this
+          property SHOULD provide a corresponding parameter named
+          <tt>$interface.name</tt> with the <a
+          href="Connection_Manager.html#Conn_Mgr_Param_Flags">DBus_Property</a>
+          flag. Clients SHOULD update this property by
+          calling <a
+            href="Account.html#org.freedesktop.Telepathy.Account.UpdateParameters">UpdateParameters</a>
+          on the relevant <a href="Account.html">Account</a> rather than
+          setting the property directly; change notification is via <a
+            href="Account.html#org.freedesktop.Telepathy.Account.AccountPropertyChanged">AccountPropertyChanged</a>.
+          </p>
+      </div>
+      #end if
+
+     $property.get_docstring()
+    </div>
+    #end for
+   </div>
+   #end if
+
+   #if $interface.tpproperties
+   <div class="outset tpproperties tpproperty">
+    <a name="tpproperties"></a>
+    <h1>Telepathy Properties</h1>
+    <div>
+     Accessed using the <a
+       href="Properties_Interface.html">org.freedesktop.Telepathy.Properties</a>
+     interface.
+    </div>
+    #for $property in $interface.tpproperties
+    <div class="inset tpproperty">
+     <a name="$property.get_anchor()"></a>
+     <span class="permalink">(<a href="$property.get_url()">Permalink</a>)</span>
+     <h2>
+      $property.short_name &mdash; $property.dbus_type
+      #if $property.type: (<a href="$property.get_type_url()" title="$property.get_type_title()">$property.get_type().short_name</a>)
+     </h2>
+     $property.get_added()
+     $property.get_changed()
+     $property.get_deprecated()
      $property.get_docstring()
     </div>
     #end for
    </div>
    #end if
 
+   #if $interface.contact_attributes
+   <div class="outset contact-attributes">
+    <a name="contact-attributes"></a>
+    <h1>Contact Attributes</h1>
+    <div>
+      Attributes that a contact can have, accessed with the
+      org.freedesktop.Telepathy.Connection.Interface.Contacts interface.
+    </div>
+    #for $token in $interface.contact_attributes
+    <div class="inset contact-attribute">
+     <a name="$token.get_anchor()"></a>
+     <span class="permalink">(<a href="$token.get_url()">Permalink</a>)</span>
+     <h2>
+      $token.name &mdash; $token.dbus_type
+      #if $token.type: (<a href="$token.get_type_url()" title="$token.get_type_title()">$token.get_type().short_name</a>)
+     </h2>
+     $token.get_added()
+     $token.get_changed()
+     $token.get_deprecated()
+     $token.get_docstring()
+    </div>
+    #end for
+   </div>
+   #end if
+
+   #if $interface.handler_capability_tokens
+   <div class="outset handler-capability-tokens">
+    <a name="handler-capability-tokens"></a>
+    <h1>Handler Capability Tokens</h1>
+    <div>
+      Tokens representing capabilities that a Client.Handler can have.
+    </div>
+    #for $token in $interface.handler_capability_tokens
+    <div class="inset handler-capability-token">
+     <a name="$token.get_anchor()"></a>
+     <span class="permalink">(<a href="$token.get_url()">Permalink</a>)</span>
+     <h2>
+      $token.name
+      #if $token.is_family
+      (etc.)
+      #end if
+     </h2>
+     $token.get_added()
+     $token.get_changed()
+     $token.get_deprecated()
+     $token.get_docstring()
+    </div>
+    #end for
+   </div>
+   #end if
 
    #if $interface.types
    <div class="outset types type">
diff --git a/doc/templates/interfaces.html b/doc/templates/interfaces.html
index 1b5f844..85504d7 100644
--- a/doc/templates/interfaces.html
+++ b/doc/templates/interfaces.html
@@ -9,6 +9,12 @@
   <div class="header">
    <h1>$spec.title</h1>
    <a href="index.html">Full</a>
+#if len($spec.generic_types) > 0
+   | <a href="generic-types.html">Generic Types</a>
+#end if
+#if len($spec.errors) > 0
+   | <a href="errors.html">Errors</a>
+#end if
    | <a href="fullindex.html">Full Index</a>
   </div>
 
@@ -21,7 +27,7 @@
   #for $interface in $spec.interfaces
    #if $interface.causes_havoc
     <li class="causes-havoc">
-   #elif $interface.deprecated
+   #elif $interface.is_deprecated
     <li class="deprecated">
    #else
     <li>
@@ -29,13 +35,26 @@
     <a href="$interface.get_url()">$interface.name</a>
     #if $interface.causes_havoc
      (unstable)
-    #elif $interface.deprecated
+    #elif $interface.is_deprecated
      (deprecated)
     #end if
    </li>
   #end for
   </ul>
 
+#if len($spec.generic_types) > 0 or len($spec.errors) > 0
+  <a name="other"></a>
+  <h3>Other</h3>
+  <ul>
+  #if len($spec.generic_types) > 0
+   <li><a href="generic-types.html">Generic Types</a></li>
+  #end if
+  #if len($spec.errors) > 0
+   <li><a href="errors.html">Errors</a></li>
+  #end if
+  </ul>
+#end if
+
   </div>
  </body>
 </html>
diff --git a/doc/templates/style.css b/doc/templates/style.css
index a02d743..8a49df6 100644
--- a/doc/templates/style.css
+++ b/doc/templates/style.css
@@ -120,6 +120,14 @@ div.handler-capability-token {
 	border: 1px solid #228822;
 }
 
+div.client-interests {
+	background-color: #729fcf;
+}
+
+div.client-interest {
+	border: 1px solid #204a87;
+}
+
 div.types {
 	background-color: #e9b96e;
 }
diff --git a/tools/doc-generator.py b/tools/doc-generator.py
index c40f224..95a8011 100755
--- a/tools/doc-generator.py
+++ b/tools/doc-generator.py
@@ -104,6 +104,10 @@ def render_template(name, namespaces, target=None):
 
 namespaces = { 'spec': spec }
 
+if len(spec.generic_types) > 0:
+    render_template('generic-types.html', namespaces)
+if len(spec.errors) > 0:
+    render_template('errors.html', namespaces)
 render_template('interfaces.html', namespaces)
 render_template('fullindex.html', namespaces)
author	Alex Merry <dev@randomguy3.me.uk>	2010-12-23 13:00:40 +0000
committer	Alex Merry <dev@randomguy3.me.uk>	2010-12-23 13:00:40 +0000
commit	02b45059914886d9dddb67bda597a646c7748dc8 (patch)
tree	a1c43f6126f9a38b95c620ed5953f0aa6b2acfec
parent	aee1bb29d20780726dc18a314bae2403e484a566 (diff)