From 02b45059914886d9dddb67bda597a646c7748dc8 Mon Sep 17 00:00:00 2001 From: Alex Merry Date: Thu, 23 Dec 2010 13:00:40 +0000 Subject: Sync spec tooling with telepathy We now have minimal differences with the upstream tooling (just index.html and style.css). --- doc/templates/devhelp.devhelp2 | 8 +- doc/templates/errors.html | 64 +++++++++++ doc/templates/fullindex.html | 4 +- doc/templates/generic-types.html | 59 ++++++++++ doc/templates/index.html | 23 +++- doc/templates/interface.html | 227 +++++++++++++++++++++++++++++++++++++++ doc/templates/interfaces.html | 23 +++- doc/templates/style.css | 8 ++ tools/doc-generator.py | 4 + 9 files changed, 413 insertions(+), 7 deletions(-) create mode 100644 doc/templates/errors.html create mode 100644 doc/templates/generic-types.html 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 #end for +#if len($spec.generic_types) > 0 + +#end if +#if len($spec.errors) > 0 + +#end if #for $obj in $spec.everything.values() + $spec.types.values() + $spec.errors.values() #for $entry in $obj.get_index_entries() #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 @@ + + + + + Errors + + + +
+

Errors

+ Interface Index + (Compact) + | Summary + | Errors +
+
+
+ +

Errors

+ + #for $error in $spec.sorted_errors + #if $error.is_deprecated + + #else + + #end if + + + + #end for +
$error.short_name + #if $error.is_deprecated: (deprecated) +
+
+ + #if $spec.errors_section + $spec.errors_section.get_docstring() + #end if + +
+ +

Errors

+ #for $error in $spec.sorted_errors +
+ + (Permalink) +

+ $error.short_name +

+ +
+ $error.name +
+ + $error.get_added() + $error.get_deprecated() + $error.get_docstring() +
+ #end for +
+
+ + + 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 $l #for $n in $g - #if $n[1].deprecated + #if $n[1].is_deprecated #else #end if $n[0] - #if $n[1].deprecated: (deprecated) + #if $n[1].is_deprecated: (deprecated) $n[1].get_type_name() 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 @@ + + + + + Generic Types + + + +
+

Generic Types

+ Interface Index + (Compact) + | Summary + | Types +
+
+
+ +

Generic Types

+ + #for $type in $spec.generic_types + #if $type.is_deprecated + + #else + + #end if + + + + + + #end for +
$type.short_name$type.get_type_name()$type.dbus_type + #if $type.is_deprecated: (deprecated) +
+
+ +
+ +

Generic Types

+ #for $type in $spec.generic_types +
+ + $type.get_type_name() (Permalink) +

+ $type.short_name — $type.dbus_type +

+ + $type.get_added() + $type.get_deprecated() + $type.get_docstring() + $type.get_breakdown() +
+ #end for +
+
+ + + 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 @@

$spec.title

Interfaces (Compact) +#if len($spec.generic_types) > 0 + | Generic Types +#end if +#if len($spec.errors) > 0 + | Errors +#end if | Full Index @@ -60,7 +66,7 @@ #end if #if $item.causes_havoc
  • - #elif $item.deprecated + #elif $item.is_deprecated
  • #else
  • @@ -68,7 +74,7 @@ $item.name #if $item.causes_havoc (unstable) - #elif $item.deprecated + #elif $item.is_deprecated (deprecated) #end if
    • @@ -80,6 +86,19 @@ #end def $output($spec.items, False) +#if len($spec.generic_types) > 0 or len($spec.errors) > 0 + +

    Other

    +
      + #if len($spec.generic_types) > 0 +
    • Generic Types
      • + #end if + #if len($spec.errors) > 0 +
    • Errors
      • + #end if +
    +#end if + 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 @@ Interface Index (Compact) | Summary + #if $interface.client_interests: | Client Interests #if $interface.docstring: | Description #if $interface.methods: | Methods #if $interface.signals: | Signals #if $interface.properties: | Properties + #if $interface.tpproperties: | Telepathy Properties + #if $interface.contact_attributes: | Contact Attributes + #if $interface.handler_capability_tokens: | Handler Capability Tokens #if $interface.types: | Types
    @@ -24,6 +28,14 @@ #if $interface.methods or $interface.signals or $interface.properties or $interface.types or $interface.tpproperties
    + #if $interface.client_interests +

    Client Interests

    + + #for $interest in $interface.client_interests + + #end for +
    $interest.name
    + #end if #if $interface.methods

    Methods

    @@ -88,6 +100,52 @@
    #end if + #if $interface.tpproperties +

    Telepathy Properties

    + + #for $property in $interface.tpproperties + + + + + #end for +
    $property.short_name + $property.dbus_type + #if $property.type: ($property.get_type().short_name) +
    + #end if + + #if $interface.contact_attributes +

    Contact Attributes

    + + #for $token in $interface.contact_attributes + + + + + #end for +
    $token.name + $token.dbus_type + #if $token.type: ($token.get_type().short_name) +
    + #end if + + #if $interface.handler_capability_tokens +

    Handler Capability Tokens

    + + #for $token in $interface.handler_capability_tokens + + + + + #end for +
    $token.name + #if $token.is_family + (etc.) + #end if + +
    + #end if #if $interface.types

    Types

    @@ -145,6 +203,27 @@ $interface.get_docstring() #end if + #if $interface.client_interests +
    + +

    Client Interests

    +
    + Set using the + AddClientInterest and + RemoveClientInterest methods. +
    + #for $interest in $interface.client_interests +
    + + (Permalink) +

    $interest.name

    + + $interest.get_docstring() +
    + #end for +
    + #end if + #if $interface.methods
    @@ -278,6 +357,62 @@
    $property.get_access()
    + #if $property.sometimes_immutable: +
    Depending on the protocol, this + property may be immutable 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 NewChannels + signals. + #else + change. + #end if +
    + #elif $property.immutable: +
    This property is + immutable 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 NewChannels + signals. + #else + change. + #end if +
    + #end if + + #if $property.sometimes_requestable: +
    Depending on the protocol, this + property may be requestable, which means that it may be + allowed in the properties hash of a channel request such as in the + CreateChannel + and + EnsureChannel + methods + on Requests + and ChannelDispatcher. + If supported on this protocol, the property should appear in either the + Fixed_Properties or Allowed_Properties of + a RequestableChannelClass + advertised by the CM.
    + #elif $property.requestable: +
    This property + is requestable, which means that it is allowed + in the properties hash of a channel request such as in the + CreateChannel + and + EnsureChannel + methods + on Requests + and ChannelDispatcher. + The property should also appear in either the Fixed_Properties + or Allowed_Properties of + a RequestableChannelClass + advertised by the CM.
    + #end if + $property.get_added() $property.get_changed() $property.get_deprecated() @@ -301,12 +436,104 @@
    #end if + #if $property.is_connection_parameter: +
    +

    Note: Connections implementing this + property SHOULD provide a corresponding parameter named + $interface.name with the DBus_Property + flag. Clients SHOULD update this property by + calling UpdateParameters + on the relevant Account rather than + setting the property directly; change notification is via AccountPropertyChanged. +

    +
    + #end if + + $property.get_docstring() +
    + #end for +
    + #end if + + #if $interface.tpproperties +
    + +

    Telepathy Properties

    +
    + Accessed using the org.freedesktop.Telepathy.Properties + interface. +
    + #for $property in $interface.tpproperties +
    + + (Permalink) +

    + $property.short_name — $property.dbus_type + #if $property.type: ($property.get_type().short_name) +

    + $property.get_added() + $property.get_changed() + $property.get_deprecated() $property.get_docstring()
    #end for
    #end if + #if $interface.contact_attributes +
    + +

    Contact Attributes

    +
    + Attributes that a contact can have, accessed with the + org.freedesktop.Telepathy.Connection.Interface.Contacts interface. +
    + #for $token in $interface.contact_attributes +
    + + (Permalink) +

    + $token.name — $token.dbus_type + #if $token.type: ($token.get_type().short_name) +

    + $token.get_added() + $token.get_changed() + $token.get_deprecated() + $token.get_docstring() +
    + #end for +
    + #end if + + #if $interface.handler_capability_tokens +
    + +

    Handler Capability Tokens

    +
    + Tokens representing capabilities that a Client.Handler can have. +
    + #for $token in $interface.handler_capability_tokens +
    + + (Permalink) +

    + $token.name + #if $token.is_family + (etc.) + #end if +

    + $token.get_added() + $token.get_changed() + $token.get_deprecated() + $token.get_docstring() +
    + #end for +
    + #end if #if $interface.types
    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 @@

    $spec.title

    Full +#if len($spec.generic_types) > 0 + | Generic Types +#end if +#if len($spec.errors) > 0 + | Errors +#end if | Full Index
    @@ -21,7 +27,7 @@ #for $interface in $spec.interfaces #if $interface.causes_havoc
  • - #elif $interface.deprecated + #elif $interface.is_deprecated
  • #else
  • @@ -29,13 +35,26 @@ $interface.name #if $interface.causes_havoc (unstable) - #elif $interface.deprecated + #elif $interface.is_deprecated (deprecated) #end if
    • #end for +#if len($spec.generic_types) > 0 or len($spec.errors) > 0 + +

    Other

    +
      + #if len($spec.generic_types) > 0 +
    • Generic Types
      • + #end if + #if len($spec.errors) > 0 +
    • Errors
      • + #end if +
    +#end if +
    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) -- cgit v1.2.3