Commit 0b377a4b authored by Emmanuel Milou's avatar Emmanuel Milou

[#2521] Integrating dbus api documentation generation in the build system + Clean up doc directory

parent b6171387
......@@ -18,6 +18,12 @@ unittest:
@echo " -- You need the cppunit devel package to compile the unitary tests."
endif
doc:
@(cd doc; make)
@echo ""
@echo "D-Bus API HTML documentation has been generated in doc/dbus-api/doc/spec"
@echo ""
indent:
@echo "Indenting code:"
if [ -f $(ASTYLERC) ] ; then \
......
......@@ -70,12 +70,12 @@ AC_CONFIG_FILES([Makefile])
dnl Unitary test section
AC_CONFIG_FILES([test/Makefile])
AC_CONFIG_FILES([ringtones/Makefile])
AC_CONFIG_FILES([man/Makefile])
AC_CONFIG_FILES([doc/Makefile \
doc/dbus-api/Makefile \
doc/doxygen/Makefile])
dnl the file stamp-h.in should be there before (instead of AC_CONFIG_HEADERS(config.h))
......
SUBDIRS = doxygen
SUBDIRS = doxygen dbus-api
.PHONY: doc
doc:
$(MAKE) -C doxygen doc
\ No newline at end of file
$(MAKE) -C doxygen doc
include $(top_srcdir)/globals.mak
XSLTPROC=xsltproc --xinclude --nonet
PYTHON=python
XMLS= $(wildcard $(top_srcdir)/src/dbus/spec/*.xml)
TEMPLATES= $(wildcard doc/templates/*)
GENERATED_FILES = \
doc/spec.html \
doc/spec/index.html
doc/spec.html: $(XMLS) tools/doc-generator.xsl
@install -d tmp/doc
$(XSLTPROC) tools/doc-generator.xsl spec/all.xml > tmp/$@
mv tmp/$@ $@
doc/spec/index.html: $(XMLS) tools/doc-generator.py tools/specparser.py $(TEMPLATES)
@install -d tmp/doc
$(PYTHON) tools/doc-generator.py spec/all.xml doc/spec sflphone-spec org.sflphone.SFLphone
all: $(GENERATED_FILES)
clean:
rm -rf $(GENERATED_FILES)
rm -rf doc/spec
rm -rf tmp
SFLphone D-Bus API documentation. Generated with xsltproc.
Wiki reference: https://projects.savoirfairelinux.com/wiki/sflphone/Dbus-API
Run Makefile to generate the HTML API documentation, from the xml interfaces in *sflphone-common/src/dbus*.
The documentation is generated in *sflphone-common/doc/dbus-api/doc/spec*
<?xml version="1.0"?>
<book xmlns="http://www.devhelp.net/book" title="$spec.title" name="$name" link="index.html">
<chapters>
#for $interface in $spec.interfaces
<sub name="$interface.name" link="$interface.get_url()"/>
#end for
<sub name="Generic Types" link="generic-types.html"/>
<sub name="Errors" link="errors.html"/>
<sub name="Full Index" link="fullindex.html"/>
</chapters>
<functions>
#for $obj in $spec.everything.values() + $spec.types.values() + $spec.errors.values()
<keyword type="$obj.devhelp_name" name="$obj.get_title()" link="$obj.get_url()" #slurp
#if $obj.deprecated: deprecated="true" #slurp
/>
#end for
</functions>
</book>
<?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.errors.values()
#if $error.deprecated
<tr class="deprecated">
#else
<tr>
#end if
<td><a href="$error.get_url()">$error.short_name</a></td>
<td>
#if $error.deprecated: (deprecated)
</td>
</tr>
#end for
</table>
</div>
<div class="outset errors error">
<a name="errors"></a>
<h1>Errors</h1>
#for $error in $spec.errors.values()
<div class="inset error">
<a name="$error.name"></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>
#from itertools import groupby
<?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>Full Index</title>
<link rel="stylesheet" href="style.css" type="text/css"/>
</head>
#set $star = []
#for $item in $spec.everything.values() + $spec.errors.values() + $spec.generic_types
#echo $star.append(($item.short_name, $item))
#slurp
#end for
#echo $star.sort(key = lambda t: t[0].title())
#slurp
## one use iterators...
#set $groups = [ (l, list(g)) for l, g in (groupby($star, key = lambda t: t[0][0].upper())) ]
#set $letters = set(map(lambda t: t[0], groups))
<body>
<div class="header">
<h1>Full Index</h1>
<a href="index.html">Interface Index</a>
(<a href="interfaces.html">Compact</a>)
#for $a in map(chr, xrange(ord('A'), ord('Z')+1))
#if $a in $letters
| <a href="#$a">$a</a>
#else
| $a
#end if
#end for
</div>
<div class="main">
<table class="summary">
#for l, g in $groups
<tr><th colspan="3"><a name="$l"></a>$l</th></tr>
#for $n in $g
#if $n[1].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)
</td>
<td>$n[1].get_type_name()</td>
<td>
#if $n[1].parent.__class__.__name__ == 'Interface': $n[1].parent.name
</td>
</tr>
#end for
#end for
<table>
</div>
</body>
</html>
<?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.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.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.name"></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>
<?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>$spec.title &mdash v$spec.version</title>
<link rel="stylesheet" href="style.css" type="text/css"/>
</head>
<body>
<div class="header">
<h1>$spec.title</h1>
<a href="#interfaces">Interfaces</a>
(<a href="interfaces.html">Compact</a>)
| <a href="generic-types.html">Generic Types</a>
| <a href="errors.html">Errors</a>
| <a href="fullindex.html">Full Index</a>
</div>
<div class="main">
<h3 class="version">Version $spec.version</h3>
<p class="copyrights">
#echo '<br/>'.join($spec.copyrights)
</p>
$spec.license
<a name="interfaces"></a>
<h3>Interfaces</h3>
<ul>
#def output($items)
#for $item in $items
#if $item.__class__.__name__ == 'Section'
<li class="chapter">$item.short_name</li>
$item.get_docstring()
<ul>
$output($item.items)
</ul>
#else
#if $item.causes_havoc
<li class="causes-havoc">
#elif $item.deprecated
<li class="deprecated">
#else
<li>
#end if
<a href="$item.get_url()">$item.name</a>
#if $item.causes_havoc
(unstable)
#elif $item.deprecated
(deprecated)
#end if
</li>
#end if
#end for
#end def
$output($spec.items)
</ul>
<a name="other"></a>
<h3>Other</h3>
<ul>
<li><a href="generic-types.html">Generic Types</a></li>
<li><a href="errors.html">Errors</a></li>
</ul>
</div>
</body>
</html>
This diff is collapsed.
<?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>$spec.title &mdash v$spec.version</title>
<link rel="stylesheet" href="style.css" type="text/css"/>
</head>
<body>
<div class="header">
<h1>$spec.title</h1>
<a href="index.html">Full</a>
| <a href="generic-types.html">Generic Types</a>
| <a href="errors.html">Errors</a>
| <a href="fullindex.html">Full Index</a>
</div>
<div class="main">
<b>Version $spec.version</b>
<a name="interfaces"></a>
<h3>Interfaces</h3>
<ul>
#for $interface in $spec.interfaces
#if $interface.causes_havoc
<li class="causes-havoc">
#elif $interface.deprecated
<li class="deprecated">
#else
<li>
#end if
<a href="$interface.get_url()">$interface.name</a>
#if $interface.causes_havoc
(unstable)
#elif $interface.deprecated
(deprecated)
#end if
</li>
#end for
</ul>
<a name="other"></a>
<h3>Other</h3>
<ul>
<li><a href="generic-types.html">Generic Types</a></li>
<li><a href="errors.html">Errors</a></li>
</ul>
</div>
</body>
</html>
html, body,
h1, h2 {
font-family: "Georgia";
margin: 0;
padding: 0;
}
h3 {
margin-top: 2pt;
margin-bottom: 2pt;
}
ul {
margin: 1ex;
margin-left: 1.5em;
padding: 0;
}
hr {
border-style: none;
color: #cccccc;
background-color: #cccccc;
height: 1px;
}
div.header {
position: fixed;
height: 4em;
background-color: AliceBlue;
width: 100%;
margin: 0;
padding: 0.5ex;
border-bottom: 1px solid black;
top: 0;
left: 0;
z-index: 1;
}
div.header h1 {
white-space: nowrap;
text-overflow: ellipsis;
overflow: hidden;
}
div.main {
margin-top: 5em;
margin-left: 1ex;
margin-right: 1ex;
margin-bottom: 1ex;
}
div.main a[name] {
position: relative;
top: -4.5em;
}
div.outset {
padding: 1ex;
margin-top: 1ex;
margin-bottom: 1ex;
}
div.inset {
background-color: white;
margin-top: 1ex;
margin-bottom: 1ex;
padding: 0.5ex;
}
div.indent {
margin-left: 1em;
}
div.methods {
background-color: #fcaf3e;
}
div.method {
border: 1px solid #f57900;
}
div.signals {
background-color: #729fcf;
}
div.signal {
border: 1px solid #3465a4;
}
div.properties {
background-color: #ad7fa8;
}
div.property {
border: 1px solid #75507b;
}
div.tpproperties {
background-color: #999999;
}
div.tpproperty {
border: 1px solid #333333;
}
div.contact-attributes {
background-color: #ccccff;
border: 1px solid #9999cc;
}
div.contact-attribute {
border: 1px solid #9999cc;
}
div.handler-capability-tokens {
background-color: #339933;
border: 1px solid #228822;
}
div.handler-capability-token {
border: 1px solid #228822;
}
div.types {
background-color: #e9b96e;
}
div.type {
border: 1px solid #c17d11;
}
div.errors {
background-color: #ef2929;
}
div.error {
border: 1px solid #cc0000;
}
div.access {
font-weight: bold;
margin-left: 1ex;
}
div.summary {
padding: 0.5ex;
background-color: #eeeeec;
border: 1px solid #d3d7cf;
}
table.summary {
margin: 1ex;
font-size: small;
}
table.summary td {
padding-right: 1ex;
}
li.chapter {
margin-top: 1ex;
font-weight: bold;
}
li.causes-havoc {
font-style: italic;
}
li.deprecated,
li.deprecated a,
table.summary tr.deprecated td,
table.summary tr.deprecated td a {
color: gray;
}
div.requires,
div.docstring {
margin: 1ex;
}
div.added {
border-left: 2px solid #4e9a06;
margin: 1ex;
padding-left: 1ex;
}
div.added span.version {
color: #4e9a06;
font-weight: bold;
}
div.changed {
border-left: 2px solid #8f5902;
margin: 1ex;
padding-left: 1ex;
}
div.changed span.version {
color: #8f5902;
font-weight: bold;
}
div.deprecated,
div.havoc {
border-left: 2px solid #a40000;
margin: 1ex;
padding-left: 1ex;
}
div.deprecated span.version,
span.warning {
color: #a40000;
font-weight: bold;
}
div.rationale {
border-left: 2px solid gray;
margin: 1ex;
padding-left: 1ex;
}
span.permalink {
float: right;
font-size: x-small;
}
.license {
clear: both;
border: 1px solid #dedede;
font-style: italic;
padding: 15px;
}
.copyrights {
clear: both;
float: right;
}
<tp:spec
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
xmlns:xi="http://www.w3.org/2001/XInclude">
<tp:title>SFLphone D-Bus Interface Specification</tp:title>
<tp:version>0.9.8</tp:version>
<tp:copyright>Copyright © 2005-2010 Savoir-faire Linux Inc</tp:copyright>
<tp:license xmlns="http://www.w3.org/1999/xhtml">
<p>This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.</p>
<p>This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.</p>
<p>You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
</tp:license>
<tp:section name="Instances Manager">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>
An Instance Manager to handle multiple clients connections. Count the number of clients actually registered to the core. When initializing your client, you need to register it against the core by using this interface.
</p>
</tp:docstring>
<xi:include href="instance-introspec.xml"/>
</tp:section>
<tp:section name="Call Manager">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>
A Call Manager to handle call-related features.
</p>
</tp:docstring>
<xi:include href="callmanager-introspec.xml"/>
</tp:section>
<tp:section name="Configuration Manager">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>
A Configuration Manager to handle account configuration, user preferences, ...
</p>
</tp:docstring>
<xi:include href="configurationmanager-introspec.xml"/>
</tp:section>
<xi:include href="generic-types.xml"/>
</tp:spec>
../../../src/dbus/callmanager-introspec.xml
\ No newline at end of file
../../../src/dbus/configurationmanager-introspec.xml
\ No newline at end of file
This diff is collapsed.
<tp:generic-types
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:simple-type name="Unix_Timestamp" type="u">
<tp:docstring>An unsigned 32-bit integer representing time as the number
of seconds elapsed since the Unix epoch
(1970-01-01T00:00:00Z)</tp:docstring>
</tp:simple-type>
<tp:simple-type name="Unix_Timestamp64" type="x">
<tp:docstring>An signed 64-bit integer representing time as the number
of seconds elapsed since the Unix epoch
(1970-01-01T00:00:00Z); negative for times before the epoch</tp:docstring>