boost_mirror/boostbook
1
0
Fork 0
mirror of https://github.com/boostorg/boostbook.git synced 2025-05-09 15:03:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Boostbook: Merge from trunk.

Browse Source 
- Template parameter documentation.
- Don't print an empty table/hr in header if there is not image or
  navigation info.
- Initial mathjax support.


[SVN r75947]
This commit is contained in:
Daniel James 2011-12-14 22:42:18 +00:00
parent 453cea92dc
commit b684ebaa7c
9 changed files with 196 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
test/doxygen/Jamfile.v2
View File

@ -3,7 +3,8 @@
# Distributed under the Boost Software License, Version 1.0. (See accompanying
# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
import doxygen ;
using boostbook ;
using doxygen ;
import os ;
doxygen autodoc

8
test/doxygen/autodoc.gold
View File

@ -1,5 +1,5 @@
<?xml version="1.0" standalone="yes"?>
<library-reference id="example_reference"><title>Example Reference</title><header name="boost/example.hpp"><namespace name="example"><class name="example"><purpose>Documentation for class example. </purpose><class name="inner_class"><data-member name="x"><type>int</type></data-member></class><enum name="class_enum"><enumvalue name="enumerator"/></enum><data-member name="integer"><type>int</type></data-member><data-member name="mutable_integer" specifiers="mutable"><type>int</type></data-member><data-member name="const_integer"><type>const int</type></data-member><data-member name="static_integer" specifiers="static"><type>int</type></data-member><data-member name="static_const_integer" specifiers="static"><type>const int</type></data-member></class><struct name="example_template"><template>
<library-reference id="example_reference"><title>Example Reference</title><header name="boost/example.hpp"><namespace name="example"><class name="example"><purpose>Documentation for class example. </purpose><class name="inner_class"><data-member name="x"><type>int</type></data-member></class><enum name="class_enum"><enumvalue name="enumerator"/></enum><typedef name="documented_type1"><description><para>This type has documentation. </para></description><type>int</type></typedef><typedef name="documented_type2"><purpose>This type has documentation. </purpose><type>long</type></typedef><typedef name="documented_type3"><description><para>This type has documentation. </para></description><type>long double</type></typedef><typedef name="undocumented_type1"><type>short</type></typedef><typedef name="undocumented_type2"><type>double</type></typedef><data-member name="integer"><type>int</type></data-member><data-member name="mutable_integer" specifiers="mutable"><type>int</type></data-member><data-member name="const_integer"><type>const int</type></data-member><data-member name="static_integer" specifiers="static"><type>int</type></data-member><data-member name="static_const_integer" specifiers="static"><type>const int</type></data-member><method-group name="public member functions"><method name="conversion-operator" cv="" specifiers="explicit"><type>int</type></method></method-group></class><struct name="example_template"><template>
<template-type-parameter name="TypeParameter"><purpose><para>A template parameter </para></purpose></template-type-parameter>
<template-nontype-parameter name="NonTypeParameter"><type>int</type><purpose><para>This is a non-type template parameter </para></purpose></template-nontype-parameter>
<template-type-parameter name="TypeParameterWithDefault"><default>int</default><purpose><para>This is a template parameter with a default argument </para></purpose></template-type-parameter>
@ -22,4 +22,8 @@ Line 1<sbr/>
This is a test function. <classname alt="example::example">Link to class</classname> <classname alt="example::example_template">Link to class template</classname> <note><para>This is a note.</para></note>
<para><emphasis role="bold">See Also:</emphasis><para><classname alt="example::example">example::example</classname> and <classname alt="example::example_template">example_template</classname> </para></para>
</para></description><requires><para>i &gt; j</para></requires><returns><para>The answer </para></returns></function></namespace><macro name="EXAMPLE" kind="functionlike"><macro-parameter name="m"/><purpose>Documentation for macro example. </purpose></macro></header></library-reference>
</para></description><requires><para>i &gt; j</para></requires><returns><para>The answer </para></returns></function><function name="namespace_func_template"><type>void</type><template>
<template-type-parameter name="TypeParameter"><purpose><para>A template parameter </para></purpose></template-type-parameter>
<template-nontype-parameter name="NonTypeParameter"><type>int</type><purpose><para>This is a non-type template parameter </para></purpose></template-nontype-parameter>
</template><description><para>Testing a function template.
</para></description></function></namespace><macro name="EXAMPLE" kind="functionlike"><macro-parameter name="m"/><purpose>Documentation for macro example. </purpose></macro></header></library-reference>

20
test/doxygen/boost/example.hpp
View File

@ -37,6 +37,16 @@ namespace example
mutable int mutable_integer;
const int const_integer;
static const int static_const_integer;
// Visual check of typedef alignment.
/** This type has documentation. */
typedef int documented_type1;
/** \brief This type has documentation. */
typedef long documented_type2;
/** This type has documentation. */
typedef long double documented_type3;
typedef short undocumented_type1;
typedef double undocumented_type2;
class inner_class {
public:
@ -47,6 +57,8 @@ namespace example
/// INTERNAL ONLY
enum internal_enum { internal_enumerator };
explicit operator int();
protected:
int protected_integer;
static int protected_static_integer;
@ -114,6 +126,14 @@ namespace example
* \see example::example and example_template
*/
int namespace_func(int i, int j);
/**
* Testing a function template.
* \tparam TypeParameter A template parameter
* \tparam NonTypeParameter This is a non-type template parameter
*/
template <typename TypeParameter, int NonTypeParameter>
void namespace_func_template();
}
#define EXAMPLE(m) The macro

4
xsl/doxygen/doxygen2boostbook.xsl
View File

@ -1170,6 +1170,10 @@
</xsl:attribute>
</xsl:if>
<xsl:if test="@explicit = 'yes'">
<xsl:attribute name="specifiers">explicit</xsl:attribute>
</xsl:if>
<!-- Conversion type -->
<type>
<xsl:value-of select="substring-after(name/text(), 'operator ')"/>

33
xsl/function.xsl
View File

@ -803,6 +803,8 @@
<xsl:apply-templates select="description/*"/>
<xsl:if test="parameter/description|signature/parameter/description|
template/template-type-parameter/purpose|
template/template-nontype-parameter/purpose|
requires|effects|postconditions|returns|throws|complexity|
notes|rationale">
<variablelist spacing="compact">
@ -839,6 +841,37 @@
</varlistentry>
</xsl:if>
<!-- Document template parameters -->
<xsl:if test="template/template-type-parameter/purpose|
template/template-nontype-parameter/purpose">
<varlistentry>
<term>Template Parameters:</term>
<listitem>
<variablelist spacing="compact">
<xsl:processing-instruction name="dbhtml">
list-presentation="table"
</xsl:processing-instruction>
<xsl:for-each select="template/template-type-parameter|
template/template-nontype-parameter">
<xsl:sort select="attribute::name"/>
<xsl:if test="purpose">
<varlistentry>
<term>
<xsl:call-template name="monospaced">
<xsl:with-param name="text" select="@name"/>
</xsl:call-template>
</term>
<listitem>
<xsl:apply-templates select="purpose/*"/>
</listitem>
</varlistentry>
</xsl:if>
</xsl:for-each>
</variablelist>
</listitem>
</varlistentry>
</xsl:if>
<!-- Document rest of function's contract -->
<xsl:for-each select="requires|effects|postconditions|returns|throws|complexity|
notes|rationale">

59
xsl/html-base.xsl
View File

@ -32,6 +32,10 @@
</xsl:choose>
</xsl:param>
<xsl:param name="boost.mathjax" select="0"/>
<xsl:param name="boost.mathjax.script"
select="'http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'"/>
<xsl:param name="admon.style"/>
<xsl:param name="admon.graphics">1</xsl:param>
<xsl:param name="boostbook.verbose" select="0"/>
@ -276,6 +280,61 @@ set toc,title
</xsl:template>
<xsl:template name="generate.html.title"/>
<xsl:template match="*" mode="detect-math">
<xsl:variable name="is-chunk">
<xsl:call-template name="chunk"/>
</xsl:variable>
<xsl:if test="$is-chunk = '0'">
<xsl:apply-templates mode="detect-math"/>
</xsl:if>
</xsl:template>
<xsl:template match="text()" mode="detect-math"/>
<xsl:template match="textobject[@role='tex']" mode="detect-math">
<xsl:text>1</xsl:text>
</xsl:template>
<xsl:template name="user.head.content">
<xsl:if test="$boost.mathjax = 1">
<xsl:variable name="has-math">
<xsl:apply-templates mode="detect-math" select="*"/>
</xsl:variable>
<xsl:if test="string($has-math) != ''">
<script type="text/javascript" src="{$boost.mathjax.script}"/>
</xsl:if>
</xsl:if>
</xsl:template>
<xsl:template match="inlinemediaobject">
<xsl:choose>
<xsl:when test="$boost.mathjax = 1 and textobject[@role='tex']">
<xsl:variable name="content" select="string(textobject[@role='tex'])"/>
<xsl:variable name="plain-content">
<xsl:choose>
<!--strip $$-->
<xsl:when test="substring($content, 1, 1) = '$' and
substring($content, string-length($content), 1) = '$'">
<xsl:value-of select="substring($content, 2, string-length($content) - 2)"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$content"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<script type="math/tex">
<xsl:value-of select="$plain-content"/>
</script>
<noscript>
<xsl:apply-imports/>
</noscript>
</xsl:when>
<xsl:otherwise>
<xsl:apply-imports/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- ============================================================ -->

54
xsl/navbar.xsl
View File

@ -14,7 +14,7 @@
<!--
boost.defaults:
*custom - only use explicitly set parameters
*none - only use explicitly set parameters
Boost - use standard boost settings, can be overridden
-->
<xsl:param name = "boost.defaults" select = "'none'"/>
@ -87,33 +87,35 @@
<xsl:variable name = "home" select = "/*[1]"/>
<xsl:variable name = "up" select = "parent::*"/>
<table cellpadding = "2" width = "100%"><tr>
<xsl:if test = "$nav.border = 'Boost'">
<xsl:attribute name = "class">boost-head</xsl:attribute>
</xsl:if>
<td valign = "top">
<xsl:if test = "boolean(normalize-space($boost.image.src)) or $nav.layout != 'none'">
<table cellpadding = "2" width = "100%"><tr>
<xsl:if test = "$nav.border = 'Boost'">
<xsl:attribute name = "style">background-color: white; width: 50%;</xsl:attribute>
<xsl:attribute name = "class">boost-head</xsl:attribute>
</xsl:if>
<xsl:if test = "boolean(normalize-space($boost.image.src))">
<img alt="{$boost.image.alt}" width="{$boost.image.w}" height="{$boost.image.h}">
<xsl:attribute name="src">
<xsl:call-template name="href.target.relative">
<xsl:with-param name="target" select="$boost.image.src"/>
</xsl:call-template>
</xsl:attribute>
</img>
</xsl:if>
</td><xsl:choose>
<xsl:when test = "$nav.layout = 'horizontal'">
<xsl:call-template name = "header.navdata-horiz"/>
</xsl:when><xsl:when test = "$nav.layout = 'vertical'">
<xsl:call-template name = "header.navdata-vert"/>
</xsl:when>
</xsl:choose>
</tr></table>
<hr/>
<td valign = "top">
<xsl:if test = "$nav.border = 'Boost'">
<xsl:attribute name = "style">background-color: white; width: 50%;</xsl:attribute>
</xsl:if>
<xsl:if test = "boolean(normalize-space($boost.image.src))">
<img alt="{$boost.image.alt}" width="{$boost.image.w}" height="{$boost.image.h}">
<xsl:attribute name="src">
<xsl:call-template name="href.target.relative">
<xsl:with-param name="target" select="$boost.image.src"/>
</xsl:call-template>
</xsl:attribute>
</img>
</xsl:if>
</td><xsl:choose>
<xsl:when test = "$nav.layout = 'horizontal'">
<xsl:call-template name = "header.navdata-horiz"/>
</xsl:when><xsl:when test = "$nav.layout = 'vertical'">
<xsl:call-template name = "header.navdata-vert"/>
</xsl:when>
</xsl:choose>
</tr></table>
<hr/>
</xsl:if>
<xsl:choose>
<xsl:when test = "$nav.flow = 'DocBook'">
<table width = "100%" class = "navheader">

5
xsl/template.xsl
View File

@ -8,6 +8,9 @@
-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:param name="template.param.brief" select="false()"/>
<!-- Determine the length of a template header synopsis -->
<xsl:template name="template.synopsis.length">
<xsl:variable name="text">
@ -235,7 +238,7 @@
<xsl:param name="parameters" select="template-type-parameter|template-varargs|template-nontype-parameter"/>
<xsl:choose>
<xsl:when test="$parameters/purpose">
<xsl:when test="$parameters/purpose and $template.param.brief">
<xsl:call-template name="template.reference.parameters.comments">
<xsl:with-param name="indentation" select="$indentation"/>
<xsl:with-param name="highlight" select="$highlight"/>

41
xsl/type.xsl
View File

@ -395,6 +395,8 @@ Unknown type element "<xsl:value-of select="local-name(.)"/>" in type.display.na
<xsl:with-param name="compact" select="$compact"/>
<xsl:with-param name="indentation" select="$indentation"/>
<xsl:with-param name="is-reference" select="false()"/>
<xsl:with-param name="max-type-length" select="$max-type-length"/>
<xsl:with-param name="max-name-length" select="$max-name-length"/>
</xsl:call-template>
</xsl:otherwise>
</xsl:choose>
@ -1055,6 +1057,43 @@ Unknown type element "<xsl:value-of select="local-name(.)"/>" in type.display.na
</xsl:call-template>
</xsl:template>
<!-- Document template parameters -->
<xsl:template name="class-templates-reference">
<xsl:if test="(template/template-type-parameter/purpose|
template/template-nontype-parameter/purpose)
and not($template.param.brief)">
<refsect2>
<title>Template Parameters</title>
<orderedlist>
<xsl:for-each select="template/template-type-parameter|
template/template-nontype-parameter">
<listitem>
<para>
<xsl:variable name="link-to">
<xsl:call-template name="generate.id"/>
</xsl:variable>
<xsl:call-template name="preformatted">
<xsl:with-param name="text">
<xsl:call-template name="template.parameter">
<xsl:with-param name="parameter" select="."/>
<xsl:with-param name="highlight" select="true()"/>
</xsl:call-template>
</xsl:with-param>
</xsl:call-template>
</para>
<xsl:if test="purpose">
<para>
<xsl:apply-templates select="purpose/*"/>
</para>
</xsl:if>
</listitem>
</xsl:for-each>
</orderedlist>
</refsect2>
</xsl:if>
</xsl:template>
<xsl:template name="member-typedefs-reference">
<!-- True if there are any non-compacted typedefs -->
<xsl:variable name="have-typedef-references"
@ -1190,7 +1229,7 @@ Unknown type element "<xsl:value-of select="local-name(.)"/>" in type.display.na
<xsl:apply-templates select="para" mode="annotation"/>
</xsl:if>
<xsl:apply-templates select="description"/>
<xsl:call-template name="class-templates-reference"/>
<xsl:call-template name="class-members-reference"/>
<xsl:apply-templates select="access" mode="namespace-reference"/>