--- a/buildframework/helium/tools/common/docs.ant.xml Fri Feb 05 11:59:41 2010 +0000
+++ b/buildframework/helium/tools/common/docs.ant.xml Thu Mar 04 15:10:37 2010 +0200
@@ -20,157 +20,43 @@
============================================================================
-->
+<!--* @package framework -->
<project name="internal.docs" xmlns:hlm="http://www.nokia.com/helium" xmlns:ivy="antlib:org.apache.ivy.ant">
<description>
Documentation generation targets.
</description>
- <property name="helium.doc.dir" location="${helium.dir}/doc" />
+ <!-- Location of documentation source.
+ @type string
+ @scope public
+ -->
+ <property name="doc.src.dir" location="${basedir}/doc" />
+
+ <!-- The location where the docs will be built.
+ @type string
+ @scope private -->
+ <property name="docs.build.dir" location="${basedir}/build/doc" />
<fileset id="python.library.files" dir="${helium.dir}">
<include name="extensions/nokia/tools/common/python/lib/**/*.py"/>
<include name="tools/common/python/lib/**/*.py"/>
- <include name="extensions/nokia/tools/dp/iCreatorDP/**/*.py"/>
+ <include name="external/helium-antlib/python/**/*.py"/>
+ <include name="extensions/nokia/external/helium-nokia-antlib/python/**/*.py"/>
</fileset>
- <!-- Generate an overview of Helium as HTML tables. -->
- <target name="overview-to-html">
- <fmpp sourceFile="${helium.doc.dir}/src/helium_overview.html.ftl"
- outputFile="${helium.build.dir}/temp/doc/helium_overview.html"
- replaceExtension="html.ftl, html" expert="true">
- <data expandProperties="yes">
- doc: xml(${helium.doc.dir}/src/helium_overview.xml)
- </data>
- </fmpp>
- </target>
-
-
- <!-- Macro to generate the tools dependency xml output. -->
- <macrodef name="createToolsTableMacro" uri="http://www.nokia.com/helium">
- <attribute name="dir"/>
- <attribute name="failonerror"/>
- <attribute name="configs"/>
- <sequential>
- <ivy:configure file="${tools.ivy.config.file}" override="true"/>
- <ivy:resolve file="${helium.dir}/config/ivy/ivy.xml" conf="@{configs}" haltonfailure="@{failonerror}"/>
- <ivy:report todir="@{dir}" outputpattern="tool-dependencies-[conf].xml"
- conf="@{configs}" xml="true" graph="false" xsl="false"/>
- </sequential>
- </macrodef>
-
-
- <!-- Generates the tools dependency xml output. used in the retrieving Helium section to list the tools used within Helium-->
- <target name="tools-rst-table">
- <hlm:createToolsTableMacro dir="${helium.build.dir}/doc/ivy" failonerror="false"
- configs="core,ido"/>
- <fmpp sourceFile="${helium.doc.dir}/src/manual/tool-dependencies.rst.ftl" includes="*.dot.ftl"
- outputFile="${helium.build.dir}/temp/doc/nokia/tool-dependencies.rst_include"
- replaceExtension="dot.ftl, dot">
- <data expandProperties="yes">
- doc: xml(${helium.build.dir}/doc/ivy/tool-dependencies-ido.xml)
- </data>
- </fmpp>
- </target>
-
-
- <!-- Create a complete dependency graph of Helium libraries.
+ <fileset id="static.doc.files" dir="${helium.dir}/doc/src">
+ <include name="conf.py"/>
+ <include name=".static"/>
+ <include name=".templates/**"/>
+ <include name="*.jpg"/>
+ <include name="*.css"/>
+ </fileset>
- Currently this does not work correctly but it is useful for future testing of repreport. -->
- <target name="libraries-dependencies">
- <ivy:settings file="${tools.ivy.config.file}"/>
- <!--<ivy:resolve file="${helium.dir}/config/ivy/ivy.xml" conf="" haltonfailure="false"/>-->
- <delete file="@{dir}/ivy-repository-report.xml"/>
- <ivy:repreport todir="${helium.build.dir}/doc/ivy" organisation="S60_SAM"
- xml="true" graph="false" xsl="false"/>
- <!--<fmpp sourceFile="${helium.doc.dir}/src/manual/tool-dependencies.rst.ftl" includes="*.dot.ftl"
- outputFile="${helium.build.dir}/temp/doc/manual/tool-dependencies.rst_include"
- replaceExtension="dot.ftl, dot">
- <data expandProperties="yes">
- doc: xml(${helium.build.dir}/doc/ivy/tool-dependencies-ido.xml)
- </data>
- </fmpp>-->
- </target>
-
-
- <!-- Generate .rst tables from the property groups in the data model. -->
- <target name="property-group-tables">
- <fmpp sourceRoot="${helium.doc.dir}/src" includes="*.dot.ftl" outputRoot="${helium.build.dir}/temp/doc/api/helium"
- replaceExtension="dot.ftl, dot">
- <data expandProperties="yes">
- doc: xml(${database.file})
- </data>
- </fmpp>
- </target>
-
-
- <!-- Generate Python API documentation using epydoc. -->
- <target name="python-apidocs">
- <mkdir dir="${helium.build.dir}/doc/api/python"/>
- <pathconvert pathsep=" " property="epydoc.python.modules.path">
- <fileset refid="python.library.files"/>
- </pathconvert>
- <echo>Python modules path: ${epydoc.python.modules.path}</echo>
- <exec executable="python" dir="${helium.build.dir}" failonerror="true">
- <arg line="${python.tools}/epydoc"/>
- <arg value="-v"/>
- <arg value="--config=${helium.dir}/config/epydoc.conf"/>
- <arg value="--exclude=sgmllib"/>
- <arg line="${epydoc.python.modules.path}"/>
- </exec>
- </target>
-
-
- <!-- Generate Java API documentation using javadoc. -->
- <target name="java-apidocs" depends="install-cruisecontrol">
- <path id="classpath-javadoc">
- <fileset dir="${helium.dir}/external/CruiseControl/lib" includes="*.jar"/>
- <fileset dir="${helium.dir}/external" includes="**/*.jar"/>
- <pathelement path="${helium.dir}/external/CruiseControl/webapps/dashboard/WEB-INF/classes"/>
- </path>
- <javadoc classpathref="classpath-javadoc"
- destdir="${helium.build.dir}/doc/api/java" useexternalfile="true">
- <packageset dir="tools/common/java/src" defaultexcludes="yes"/>
- <packageset dir="tools/common/java/test" defaultexcludes="yes"/>
- <doctitle><![CDATA[<h1>API Documentation</h1>]]></doctitle>
- </javadoc>
- </target>
-
-
- <!-- Generate Ant API documentation using antdoclet. -->
- <target name="antdoclet" description="Generate Ant Task/Types documentation">
- <path id="doclet-classpath">
- <pathelement path="${java.class.path}/"/>
- <pathelement path="${helium.dir}/external/CruiseControl/webapps/dashboard/WEB-INF/classes"/>
- </path>
- <mkdir dir="${helium.build.dir}/doc/api/ant"/>
-
- <!-- First copy the "static" resources (images, static html files) -->
- <copy todir="${helium.build.dir}/doc/api/ant" overwrite="true">
- <fileset dir="${helium.doc.dir}/src/antdoclet/html">
- <exclude name="*.vm"/>
- </fileset>
- </copy>
-
- <!-- Now invoke AntDoclet to generate the "dynamic" content from the templates -->
- <javadoc access="private" sourcepath="${helium.dir}/tools/common/java/src/"
- destdir="${helium.build.dir}/doc/api/ant"
- packagenames="com.nokia.ant,com.nokia.ant.filters,com.nokia.ant.types.imaker,com.nokia.ant.types,com.nokia.ant.listerner,com.nokia.ant.taskdefs,com.nokia.ant.taskdefs.ccm.commands,com.nokia.cruisecontrol,com.nokia.cruisecontrol.sourcecontrol,com.nokia.fmpp,nokia.ivy"
- docletpathref="doclet-classpath" source="1.6"
- useexternalfile="true">
- <doclet name="com.neuroning.antdoclet.AntDoclet">
- <param name="-doctitle" value="${build.name}" />
- <param name="-templatesdir" value="${helium.doc.dir}/src/antdoclet/html"/>
- <param name="-templates" value="main.vm"/>
- </doclet>
- </javadoc>
- <move file="velocity.log" tofile="build/velocity.log" failonerror="false"/>
- </target>
-
<!-- Cleans the Helium API documentation. -->
- <target name="clean-helium-apidoc">
- <delete dir="${helium.build.dir}/doc/api/helium"/>
- <delete dir="${helium.build.dir}/temp/doc/api/helium"/>
+ <target name="clean-helium-apidocs">
+ <delete dir="${docs.build.dir}/api/helium"/>
+ <delete dir="${docs.build.dir}/temp/doc/api/helium"/>
</target>
@@ -179,224 +65,52 @@
This includes creating a cmap file that is included in the HTML document,
so the boxes in the image are linked to their targets. -->
<target name="helium-api-dependency-images">
- <mkdir dir="${helium.build.dir}/doc/api/helium"/>
- <fmpp sourceRoot="${helium.doc.dir}/src/api" includes="*.dot.ftl" outputRoot="${helium.build.dir}/temp/doc/api/helium"
+ <mkdir dir="${docs.build.dir}/api/helium"/>
+ <fmpp sourceRoot="${helium.dir}/doc/src/api" includes="*.dot.ftl" outputRoot="${docs.build.dir}/temp/doc/api/helium"
replaceExtension="dot.ftl, dot">
<data expandProperties="yes">
doc: xml(${database.file})
</data>
</fmpp>
<for param="dot.file" parallel="true" threadCount="${number.of.threads}">
- <fileset dir="${helium.build.dir}/temp/doc/api/helium" includes="*.dot"/>
+ <fileset dir="${docs.build.dir}/temp/doc/api/helium" includes="*.dot"/>
<sequential>
<echo>Processing dot file: @{dot.file}</echo>
- <exec executable="dot" dir="${helium.build.dir}/temp/doc/api/helium">
+ <exec executable="dot" dir="${docs.build.dir}/temp/doc/api/helium">
<arg line="-Tcmap @{dot.file} -O"/>
</exec>
- <exec executable="dot" dir="${helium.build.dir}/doc/api">
+ <exec executable="dot" dir="${docs.build.dir}/api">
<arg line="-Tpng @{dot.file} -O"/>
</exec>
</sequential>
</for>
- <move todir="${helium.build.dir}/doc/api" overwrite="true">
- <fileset dir="${helium.build.dir}/temp/doc/api" includes="*.dot.png"/>
+ <move todir="${docs.build.dir}/api/helium" overwrite="true">
+ <fileset dir="${docs.build.dir}/temp/doc/api/helium" includes="*.dot.png"/>
</move>
</target>
<!-- Builds the HTML files for the Helium API documentation. -->
<target name="helium-api-html-docs">
- <mkdir dir="${helium.build.dir}/doc/api/helium"/>
- <copy todir="${helium.build.dir}/temp/doc/api/helium" overwrite="true">
- <fileset dir="${helium.doc.dir}/src/api"/>
+ <mkdir dir="${docs.build.dir}/api/helium"/>
+ <copy todir="${docs.build.dir}/temp/doc/api/helium" overwrite="true">
+ <fileset dir="${helium.dir}/doc/src/api"/>
</copy>
- <xslt in="${data.model.file}" out="${data.model.parsed}" style="${data.model.xsl}"/>
- <hlm:parsemodel output="${helium.build.dir}/helium_data_model.xml_parsed" input="${data.model.parsed}"/>
- <fmpp sourceRoot="${helium.build.dir}/temp/doc/api/helium" excludes="*.dot.ftl,**/*.dot,**/*.cmap,*.bak"
- outputRoot="${helium.build.dir}/doc/api/helium"
+ <fmpp sourceRoot="${docs.build.dir}/temp/doc/api/helium" excludes="*.dot.png,*.dot.ftl,**/*.dot,**/*.cmap,*.bak"
+ outputRoot="${docs.build.dir}/api/helium"
replaceExtension="html.ftl, html">
<data expandProperties="yes">
ant: antProperties()
doc: xml(${database.file})
- data: xml(${helium.build.dir}/helium_data_model.xml_parsed)
</data>
</fmpp>
</target>
<!-- Builds the Helium API documentation. -->
- <target name="helium-apidocs" depends="clean-helium-apidoc,database,
- find-python-dependencies,helium-api-dependency-images,helium-api-html-docs"/>
-
- <!-- Builds the Helium API documentation for customer. -->
- <target name="customer-apidocs">
- <mkdir dir="${helium.build.dir}"/>
-
- <antcall target="helium-apidocs">
- <param name="helium.dir" value="."/>
- <param name="home.files.only" value="true"/>
- <param name="database.file" location="${helium.build.dir}/database.xml"/>
- </antcall>
- <!--
- <antform title="login information">
- <textProperty label="password:" property="noe.password" password="true"/>
- </antform>
-
- <antcall target="upload-docs">
- <param name="helium.dir" value="."/>
- <param name="documentation.path.root" value="/var/local/www/helium/doc/${customer}"/>
- </antcall>
- -->
- </target>
-
- <!-- Generate documentation from the source code. -->
- <target name="apidocs" depends="python-apidocs,helium-apidocs,java-apidocs,antdoclet,apidocs-search"/>
-
- <!-- Macro to generate html docs from rst. -->
- <macrodef name="rstMacro" uri="http://www.nokia.com/helium">
- <attribute name="version" default="${helium.version}"/>
- <attribute name="src" default="${helium.build.dir}/temp/doc"/>
- <attribute name="output" default="${helium.build.dir}/doc"/>
- <sequential>
- <property name="sphinx.lib.dir" location="${helium.dir}/external/python/lib/common/Sphinx-0.5.1-py2.5.egg/sphinx" />
- <if>
- <available file="${nokia.python.tools}/sphinxfixsearch.diff"/>
- <then>
- <patch patchfile="${nokia.python.tools}/sphinxfixsearch.diff" originalfile="${sphinx.lib.dir}/search.py"/>
- </then>
- </if>
- <exec executable="python" failonerror="${failonerror}">
- <arg file="${python.dir}/common/sphinx-build.py"/>
- <arg value="-b" />
- <arg value="html" />
- <arg value="-D" />
- <arg value="version=@{version}" />
- <arg value="-D" />
- <arg value="release=@{version}" />
- <arg file="@{src}" />
- <arg file="@{output}" />
- </exec>
- <if>
- <available file="${nokia.python.tools}/sphinxfixsearch.diff"/>
- <then>
- <patch reverse="true" patchfile="${nokia.python.tools}/sphinxfixsearch.diff" originalfile="${sphinx.lib.dir}/search.py"/>
- </then>
- </if>
- </sequential>
- </macrodef>
+ <target name="helium-apidocs" depends="clean-helium-apidocs,database,
+ helium-api-dependency-images,helium-api-html-docs"/>
- <!-- Generate rst files for docs -->
- <target name="prep-textdocs" depends="clean-doc-dir,overview-to-html,tools-rst-table,dependency-diagram,dependency-logs,release-diff,helium-user-graph">
- <mkdir dir="${helium.build.dir}/doc"/>
-
- <delete dir="${helium.build.dir}/doc/.doctrees"/>
- <delete file="${helium.build.dir}/doc/searchindex.json"/>
-
- <copy todir="${helium.build.dir}/doc/images">
- <fileset dir="${helium.doc.dir}/images"/>
- </copy>
-
- <!-- Temporarily copy the image directory so that doc generation will complete happily. -->
- <copy todir="${helium.build.dir}/temp/doc/images">
- <fileset dir="${helium.build.dir}/doc/images"/>
- </copy>
- <copy todir="${helium.build.dir}/temp/doc">
- <fileset dir="${helium.doc.dir}/src">
- <include name="**/*.rst"/>
- <include name="**/*.css"/>
- <include name="**/*.jpg"/>
- <include name="**/*.dot"/>
- </fileset>
- </copy>
- <copy todir="${helium.build.dir}/temp/doc/nokia" failonerror="false">
- <fileset dir="${nokia.dir}/doc/src">
- <include name="**/*.rst"/>
- <include name="**/*.css"/>
- <include name="**/*.jpg"/>
- </fileset>
- </copy>
-
- <mkdir dir="${helium.build.dir}/temp/doc/minibuilds"/>
- <copy todir="${helium.build.dir}/temp/doc/minibuilds" failonerror="false">
- <fileset dir="${helium.dir}/tests/minibuilds/">
- <include name="*/doc/**/*"/>
- </fileset>
- </copy>
-
- <fmpp sourceFile="${helium.doc.dir}/src/quick_start_guide.rst.ftl" outputFile="${helium.build.dir}/temp/doc/quick_start_guide.rst">
- <data expandProperties="yes">
- ant: antProperties()
- </data>
- </fmpp>
-
- <fileset id="internal.ref.minibuilds" dir="${helium.build.dir}/temp/doc/minibuilds" includes="*/**/index.rst"/>
- <fmpp sourceFile="${helium.doc.dir}/src/minibuilds.rst.ftl"
- outputFile="${helium.build.dir}/temp/doc/minibuilds/index.rst">
- <data expandProperties="yes">
- project: antProject()
- </data>
- </fmpp>
- <fmpp sourceFile="${helium.doc.dir}/src/index.rst.ftl" outputFile="${helium.build.dir}/temp/doc/index.rst">
- <data expandProperties="yes">
- ant: antProperties()
- </data>
- </fmpp>
- <fmpp sourceFile="${helium.doc.dir}/src/manual/APIs.rst.ftl" outputFile="${helium.build.dir}/temp/doc/manual/APIs.rst">
- <data expandProperties="yes">
- ant: antProperties()
- </data>
- </fmpp>
- <fmpp sourceFile="${helium.doc.dir}/src/manual/stages.rst.ftl" outputFile="${helium.build.dir}/temp/doc/manual/stages.rst">
- <data expandProperties="yes">
- ant: antProperties()
- </data>
- </fmpp>
-
- <copy todir="${helium.build.dir}/temp/doc">
- <fileset dir="${helium.doc.dir}/src">
- <include name="conf.py"/>
- <include name=".static"/>
- <include name=".templates/**"/>
- <include name="*.jpg"/>
- </fileset>
- </copy>
-
- <!-- Including Helium antlib doc -->
- <mkdir dir="${helium.build.dir}/temp/doc/helium-antlib"/>
- <copy todir="${helium.build.dir}/temp/doc/helium-antlib" failonerror="false">
- <fileset dir="${helium.dir}/external/helium-antlib/doc/src">
- <include name="**/*.rst"/>
- <include name="**/*.css"/>
- <include name="**/*.jpg"/>
- </fileset>
- </copy>
-
- <for param="dot.file">
- <fileset dir="${helium.build.dir}/temp/doc/manual" includes="*.dot"/>
- <sequential>
- <exec executable="dot">
- <arg line="-Tpng @{dot.file} -O"/>
- </exec>
- </sequential>
- </for>
- </target>
-
- <!-- Generate HTML documentation from .rst documents with Sphinx.
-
- All doc .rst files should be generated or copied into build/temp/doc before being processed into HTML.
- -->
- <target name="textdocs" depends="prep-textdocs">
- <hlm:rstMacro />
-
- <copy file="${database.file}" todir="${helium.build.dir}/doc"/>
- <copy file="${helium.build.dir}/temp/doc/default.css" todir="${helium.build.dir}/doc/_static" overwrite="true"/>
- <copy file="${helium.build.dir}/temp/doc/helium_pallot_small.jpg" todir="${helium.build.dir}/doc/_static" overwrite="true"/>
- <copy todir="${helium.build.dir}/doc" overwrite="true">
- <fileset dir="${helium.doc.dir}/src">
- <include name="**/*.zip"/>
- </fileset>
- </copy>
- </target>
<!-- Generate search index for apis -->
<target name="apidocs-search">
@@ -405,7 +119,7 @@
import os
import codecs
#import traceback
-for root, dirs, files in os.walk(r'${helium.build.dir}/doc/api', topdown=False):
+for root, dirs, files in os.walk(r'${docs.build.dir}/api', topdown=False):
for fname in files:
if '.html' in fname:
filename = os.path.abspath(os.path.join(root, fname))
@@ -428,412 +142,157 @@
os.remove(rstfilename)
</hlm:python>
- <move todir="${helium.build.dir}/temp_search/doc" overwrite="true">
- <fileset dir="${helium.build.dir}/doc/api">
+ <move todir="${docs.build.dir}/temp_search/doc" overwrite="true">
+ <fileset dir="${docs.build.dir}/api">
<include name="**/*.rst"/>
</fileset>
</move>
- <move todir="${helium.build.dir}/doc/api_backup" overwrite="true">
- <fileset dir="${helium.build.dir}/doc/api"/>
+ <move todir="${docs.build.dir}/api_backup" overwrite="true">
+ <fileset dir="${docs.build.dir}/api"/>
</move>
- <copy file="${helium.doc.dir}/src/api/apisearchindex.rst" tofile="${helium.build.dir}/temp_search/doc/index.rst"/>
+ <copy file="${helium.dir}/doc/src/api/apisearchindex.rst" tofile="${docs.build.dir}/temp_search/doc/index.rst"/>
- <copy todir="${helium.build.dir}/temp_search/doc">
- <fileset dir="${helium.doc.dir}/src">
- <include name="conf.py"/>
- <include name=".static"/>
- <include name=".templates/**"/>
- <include name="*.jpg"/>
- </fileset>
+ <copy todir="${docs.build.dir}/temp_search/doc">
+ <fileset refid="static.doc.files"/>
</copy>
- <hlm:rstMacro src="${helium.build.dir}/temp_search/doc" output="${helium.build.dir}/doc/api"/>
+ <hlm:rstMacro src="${docs.build.dir}/temp_search/doc" output="${docs.build.dir}/api"/>
- <move todir="${helium.build.dir}/doc/api" overwrite="true">
- <fileset dir="${helium.build.dir}/doc/api_backup"/>
+ <move todir="${docs.build.dir}/api" overwrite="true">
+ <fileset dir="${docs.build.dir}/api_backup"/>
</move>
</target>
+
- <!-- Generate all documentation. -->
- <target name="add-policies-to-docs" unless="env.HLM_SUBCON">
- <hlm:updatePolicy policy="7" filename="distribution.policy.S60">
- <dirset dir="${helium.dir}" includes="${helium.build.dir}/doc/**/*"/>
- </hlm:updatePolicy>
- </target>
+ <!-- Generate API documentation from the source code. -->
+ <target name="apidocs" depends="helium-apidocs,apidocs-search"/>
- <!-- Creates XML and .rst documents describing the difference between
- this version of Helium and the previous major release. -->
- <target name="release-diff" depends="database" unless="env.HLM_SUBCON">
- <mkdir dir="${helium.build.dir}/doc"/>
- <property name="last.major.release.database.url" value="${documentation.url.root}/${last.major.helium.version}/database.xml"/>
- <hlm:python>
-import urllib
-import helium.documentation
-
-old_db_file = urllib.urlopen(r'${last.major.release.database.url}')
-writer = helium.documentation.APIDeltaWriter(old_db_file, r'${database.file}')
-writer.write(r'${helium.build.dir}/doc/api_changes.xml')
- </hlm:python>
- <fmpp sourceFile="${helium.doc.dir}/src/api_changes.rst.ftl" outputFile="${helium.build.dir}/temp/doc/api_changes.rst">
- <data expandProperties="yes">
- doc: xml(${helium.build.dir}/doc/api_changes.xml)
- old_release: ${last.major.helium.version}
- new_release: ${helium.version}
- </data>
- </fmpp>
- </target>
-
- <!-- Generate docs for Symbian Foundataion -->
- <target name="docs-sf">
- <delete dir="${helium.build.dir}"/>
- <antcall target="helium-subcon-release"/>
- <unzip src="${helium.build.dir}/helium_${helium.version}_subcon.zip" dest="${helium.build.dir}/helium_${helium.version}_subcon" overwrite="true" />
- <!---->
- <exec executable="cmd" dir="${helium.build.dir}/helium_${helium.version}_subcon/helium">
- <env key="HELIUM_HOME" value="${helium.build.dir}/helium_${helium.version}_subcon/helium"/>
- <env key="PYTHONPATH" value="${env.PYTHONPATH}"/>
- <env key="ANT_ARGS" value="${env.ANT_ARGS}"/>
- <arg line="/C hlm.bat"/>
- <arg value="docs"/>
- <arg value="-Dpython.tools=${python.tools}"/>
- <arg value="-Dsf=true"/>
- </exec>
- </target>
-
- <!-- generate all the user documentation for helium -->
- <target name="docs" depends="clean-doc-dir,database,apidocs,textdocs,add-policies-to-docs"/>
-
- <!-- Clean old build/doc dir. -->
- <target name="clean-doc-dir">
- <delete dir="build/doc"/>
- <delete dir="build/temp/doc"/>
- </target>
-
- <!-- Connect to home drive if it is not connected for .netrc file. -->
- <target name="check-home-drive">
- <exec executable="cmd">
- <arg value="/c"/>
- <arg value="${helium.dir}/tools/common/bin/check_home_drv.bat"/>
- <arg value=">nul"/>
- </exec>
- </target>
-
- <!-- Upload generated HTML docs to the Helium server. -->
- <target name="upload-docs" depends="check-home-drive">
- <property name="documentation.path" value="${documentation.path.root}"/>
- <property name="docs.zip" value="${helium.build.dir}/helium-docs.zip"/>
-
- <!-- Python API docs. -->
- <delete file="${docs.zip}"/>
- <zip destfile="${docs.zip}">
- <fileset dir="${helium.build.dir}/doc" includes="**/*"/>
- </zip>
- <sshexec host="${documentation.host}"
- username="${user.name}"
- keyfile="${env.HOME}/.ssh/id_rsa_openssh.ppk"
- trust="true"
- command="mkdir -p ${documentation.path}"/>
- <scp todir="${user.name}@${documentation.host}:${documentation.path}"
- keyfile="${env.HOME}/.ssh/id_rsa_openssh.ppk"
- passphrase=""
- trust="true"
- sftp="true"
- file="${docs.zip}"/>
- <sshexec host="${documentation.host}"
- username="${user.name}"
- keyfile="${env.HOME}/.ssh/id_rsa_openssh.ppk"
- trust="true"
- command="cd ${documentation.path}; unzip -u -o helium-docs.zip"/>
- </target>
+ <!-- Macro to generate HTML docs from rst. -->
+ <macrodef name="rstMacro" uri="http://www.nokia.com/helium">
+ <attribute name="version" default="${helium.version}"/>
+ <attribute name="src" default="${docs.build.dir}/temp/doc"/>
+ <attribute name="output" default="${docs.build.dir}"/>
+ <sequential>
+ <property name="sphinx.lib.dir" location="${helium.dir}/external/python/lib/common/Sphinx-0.5.1-py2.5.egg/sphinx" />
+ <if>
+ <available file="${nokia.python.tools}/sphinxfixsearch.diff"/>
+ <then>
+ <patch patchfile="${nokia.python.tools}/sphinxfixsearch.diff" originalfile="${sphinx.lib.dir}/search.py"/>
+ </then>
+ </if>
+ <if>
+ <resourcecount when="greater" count="0">
+ <fileset dir="@{src}" includes="**/*.rst"/>
+ </resourcecount>
+ <then>
+ <exec executable="python" failonerror="true">
+ <arg file="${python.dir}/common/sphinx-build.py"/>
+ <arg value="-b" />
+ <arg value="html" />
+ <arg value="-D" />
+ <arg value="version=@{version}" />
+ <arg value="-D" />
+ <arg value="release=@{version}" />
+ <arg file="@{src}" />
+ <arg file="@{output}" />
+ </exec>
+ </then>
+ </if>
+ <if>
+ <available file="${nokia.python.tools}/sphinxfixsearch.diff"/>
+ <then>
+ <patch reverse="true" patchfile="${nokia.python.tools}/sphinxfixsearch.diff" originalfile="${sphinx.lib.dir}/search.py"/>
+ </then>
+ </if>
+ </sequential>
+ </macrodef>
- <!-- Upload generated HTML docs to the Helium server. -->
- <target name="upload-release-docs">
- <property name="documentation.path" value="${documentation.path.root}/${helium.version}"/>
- <antcall target="upload-docs"/>
- </target>
-
-
- <!-- create slides from images -->
- <target name="slides">
- <mkdir dir="${helium.build.dir}/slides"/>
-
- <copy todir="${helium.build.dir}/slides">
- <fileset dir="${helium.doc.dir}/slides"/>
+ <!-- Generate rst files for docs -->
+ <target name="prep-textdocs">
+ <echo>Building docs into ${docs.build.dir}.</echo>
+ <mkdir dir="${docs.build.dir}/images"/>
+
+ <delete dir="${docs.build.dir}/.doctrees"/>
+ <delete file="${docs.build.dir}/searchindex.json"/>
+
+ <copy todir="${docs.build.dir}/images" failonerror="false">
+ <fileset dir="${doc.src.dir}/images"/>
+ </copy>
+
+ <!-- Temporarily copy the image directory so that doc generation will complete happily.-->
+ <copy todir="${docs.build.dir}/temp/doc/images" failonerror="false">
+ <fileset dir="${docs.build.dir}/images"/>
</copy>
- <copy todir="${helium.build.dir}/slides/images">
- <fileset dir="${helium.doc.dir}/slides/images"/>
- </copy>
-
- <for param="document">
- <fileset dir="${helium.build.dir}/slides" includes="**/*.rst"/>
- <sequential>
- <propertyregex property="document.no.ext" input="@{document}" regexp="\.rst$" replace="" override="true"/>
- <if>
- <not>
- <uptodate srcfile="@{document}" targetfile="${document.no.ext}.html"/>
- </not>
- <then>
- <echo>Building doc: @{document}</echo>
- <exec executable="python" dir="${helium.doc.dir}" failonerror="${failonerror}">
- <arg value="${nokia.python.tools}/rst2s5.py"/>
- <arg value="@{document}"/>
- <arg value="${document.no.ext}.html"/>
- </exec>
- </then>
- </if>
- </sequential>
- </for>
- </target>
-
+ <if>
+ <available file="${doc.src.dir}/src"/>
+ <then>
+ <copy todir="${docs.build.dir}/temp/doc">
+ <fileset dir="${doc.src.dir}/src">
+ <include name="**/*.rst"/>
+ <include name="**/*.css"/>
+ <include name="**/*.jpg"/>
+ <include name="**/*.dot"/>
+ </fileset>
+ </copy>
+
+ <!--<fileset id="internal.ref.minibuilds" dir="${docs.build.dir}/temp/doc/minibuilds" includes="*/**/index.rst"/>-->
+ <fmpp sourceRoot="${doc.src.dir}/src"
+ outputRoot="${docs.build.dir}/temp/doc" includes="*.rst.ftl" removeExtensions="ftl" excludes="api_changes.rst.ftl,minibuilds.rst.ftl">
+ <data expandProperties="yes">
+ ant: antProperties()
+ project: antProject()
+ </data>
+ </fmpp>
+ </then>
+ </if>
- <!-- Generate HTML documentation from .rst documents.
-
- TODO: Remove this old method. -->
- <target name="textdocs-old" depends="overview-to-html">
- <mkdir dir="${helium.build.dir}/doc"/>
- <copy todir="${helium.build.dir}/doc-old">
- <fileset dir="${helium.doc.dir}/src" excludes="cover.rst"/>
- <fileset dir="${nokia.dir}/doc/src"/>
+ <!-- Copy static content files from Helium -->
+ <copy todir="${docs.build.dir}/temp/doc">
+ <fileset refid="static.doc.files"/>
</copy>
- <copy todir="${helium.build.dir}/doc-old/images">
- <fileset dir="${helium.doc.dir}/images"/>
- </copy>
-
- <for param="document">
- <fileset dir="${helium.build.dir}/doc-old">
- <include name="**/*.rst" />
- <exclude name="index.rst" /><!-- index.rst is the top-level doc for new-style docs -->
- </fileset>
+ <for param="dot.file">
+ <fileset dir="${docs.build.dir}/temp/doc" includes="manual/*.dot"/>
<sequential>
- <propertyregex property="document.no.ext" input="@{document}" regexp="\.rst$" replace="" override="true"/>
- <if>
- <not>
- <uptodate srcfile="@{document}" targetfile="${document.no.ext}.html"/>
- </not>
- <then>
- <echo>Building doc: @{document}</echo>
- <exec executable="python" dir="${helium.doc.dir}" failonerror="${failonerror}">
- <!--<env key="PYTHONPATH" value="${helium.dir}\${python25.lib};tools\common\python\lib"/>-->
- <arg value="${nokia.python.tools}\rst2html.py"/>
- <arg line="--traceback --no-toc-backlinks"/>
- <!-- -stylesheet-path nokia_style.css -->
- <arg value="@{document}"/>
- <arg value="${document.no.ext}.html"/>
- </exec>
- </then>
- </if>
+ <echo>Building dot file: @{dot.file}</echo>
+ <exec executable="dot">
+ <arg line="-Tpng @{dot.file} -O"/>
+ </exec>
</sequential>
</for>
</target>
- <!-- Search Python internal module used in helium -->
- <target name="find-python-dependencies" depends="database">
- <hlm:assertPropertySet property="helium.dir" message="Property helium.dir is not defined." />
- <hlm:assertPropertySet property="database.file" message="Property database.file is not defined."/>
- <hlm:python>
-from __future__ import with_statement
-import re
-import os
-import string
-import amara
-import codecs
-import ant
-import docs
+ <!-- Generate HTML documentation from .rst documents with Sphinx.
+
+ All doc .rst files should be generated or copied into build/temp/doc before being processed into HTML.
+ -->
+ <target name="textdocs" depends="prep-textdocs">
+ <hlm:rstMacro />
+
+ <copy file="${database.file}" todir="${docs.build.dir}"/>
+ <copy file="${docs.build.dir}/temp/doc/default.css" todir="${docs.build.dir}/_static" overwrite="true" failonerror="true"/>
+ <copy file="${docs.build.dir}/temp/doc/helium_pallot_small.jpg" todir="${docs.build.dir}/_static" overwrite="true"/>
+ <copy todir="${docs.build.dir}" overwrite="true">
+ <fileset dir="${doc.src.dir}/src">
+ <include name="**/*.zip"/>
+ </fileset>
+ </copy>
+ </target>
-setpath = r'${helium.dir}'+'/tools'
-
-print "Searching under "+setpath
-
-dbPath = r'${database.file}'
-dbPath = 'file:///'+ dbPath.replace('\\','/')
-dbPrj = amara.parse(dbPath)
-
-docs.find_python_dependencies(setpath, dbPath, dbPrj)
-
-file_object = codecs.open(r'${database.file}', 'w', "utf_8")
-file_object.write(dbPrj.xml(indent=u"yes"))
-file_object.close()
- </hlm:python>
+
+ <!-- Clean old build/doc dir. -->
+ <target name="clean-docs">
+ <delete dir="${docs.build.dir}"/>
</target>
- <!-- Reads the Java libraries and extracts a list of their versions. -->
- <target name="library-versions">
- <script language="jython" setbeans="false">
-import java.io
-import java.util.jar
-antlibsDir = java.io.File('external/antlibs')
-print antlibsDir
-jarFiles = antlibsDir.listFiles()
-for jar in jarFiles:
- if jar.getName().endswith('jar'):
- jarFile = java.util.jar.JarFile(jar)
- manifest = jarFile.getManifest()
- attributes = manifest.getMainAttributes()
- implementationVersion = attributes.getValue('Implementation-Version')
- print jar.getName() + ': ' + str(implementationVersion)
- </script>
- </target>
-
- <!-- Generates a subcon dependancy diagram based on Egg and Jars files -->
- <target name="dependency-diagram-subcon">
- <fileset id="subcon.jar.files" dir="${helium.dir}">
- <include name="external/antlibs/*.jar"/>
- <include name="external/jep/**/*.jar"/>
- <include name="external/helium-antlib/bin/**/*.jar"/>
- <include name="tools/**/*.jar"/>
- </fileset>
- <antcall target="dependency-diagram">
- <reference refid="subcon.jar.files" torefid="jar.files"/>
- <param name="python.exclude.dir" value="${helium.dir}\external\python\lib\2.5\internal"/>
- <param name="dependency.grph" value="${helium.build.dir}/doc/images/dependencies_subcon.grph"/>
- <param name="subcon" value="true"/>
- </antcall>
- </target>
-
- <fileset id="jar.files" dir="${helium.dir}">
- <include name="external/antlibs/**/*.jar"/>
- <include name="external/jep/**/*.jar"/>
- <include name="external/helium-antlib/**/*.jar"/>
- <include name="tools/**/*.jar"/>
- <include name="extensions/nokia/external/antlibs/**/*.jar"/>
- </fileset>
-
- <!-- Generates a dependancy diagram based on Egg and Jars files -->
- <target name="dependency-diagram">
- <mkdir dir="${helium.build.dir}/doc/images"/>
- <mkdir dir="${temp.build.dir}"/>
- <property name="dependency.grph" value="${helium.build.dir}/doc/images/dependencies.grph"/>
-
- <!---->
- <copy todir="${temp.build.dir}/dependencylibs" flatten="true">
- <fileset refid="jar.files"/>
- </copy>
-
- <hlm:antdependency outputFile="${temp.build.dir}/antdependencies.grph">
- <fileset dir="${temp.build.dir}/dependencylibs" includes="*.jar"/>
- </hlm:antdependency>
-
- <taskdef name="jaranalyzer" classname="com.kirkk.analyzer.textui.JarAnalyzerTask"/>
- <jaranalyzer srcdir="${temp.build.dir}/dependencylibs" destfile="${dependency.grph}" summaryclass="com.kirkk.analyzer.textui.DOTSummary"/>
-
- <loadfile srcfile="${temp.build.dir}/antdependencies.grph" property="antdependencies"/>
- <replace file="${dependency.grph}" token="}" value="${antdependencies}}"/>
-
- <antcall target="dependency-grouping"/>
-
- <exec executable="dot">
- <arg line="-Tpng -Grankdir=LR -Nshape=box -Nfontsize=9 -Nwidth=0.3 -Nheight=0.2 ${dependency.grph} -O"/>
- </exec>
-
- <delete dir="${temp.build.dir}/dependencylibs"/>
-
- </target>
-
- <!-- Private: -->
- <target name="dependency-grouping">
- <property name="dependency.grph" value="${helium.build.dir}/doc/images/dependencies.grph"/>
- <mkdir dir="${helium.build.dir}/doc/images"/>
- <property name="python.internal.dir" value="${nokia.dir}\external\python\lib\2.5"/>
- <property name="subcon" value=""/>
- <property name="ivy.xml.file" value="${helium.dir}/config/ivy/ivy.xml"/>
- <hlm:python>
-import os
-import dependancygraph
-
-dependancygraph.createGraph(r'${ivy.xml.file}', r'${dependency.grph}', r'${python.dir}', r'${python.internal.dir}', r'${subcon}')
- </hlm:python>
- <!--
- <exec executable="dot">
- <arg line="-Tpng -Grankdir=LR -Nshape=box -Nfontsize=9 -Nwidth=0.3 -Nheight=0.2 ${dependency.egg.grph} -O"/>
- </exec>
- -->
- </target>
-
- <!-- Generates a dependancy diagram of ant projects to helium external files -->
- <target name="dependency-external">
- <property name="dependency.external.grph" value="${helium.build.dir}/doc/images/dependencies_external.grph"/>
- <copy file="${database.file}" tofile="${database.file}.parsed" overwrite="true">
- <filterchain>
- <expandproperties/>
- </filterchain>
- </copy>
- <hlm:python>
-import os
-import dependancygraph
-
-dependancygraph.externalDependancies(r'${database.file}.parsed', r'${dependency.external.grph}')
- </hlm:python>
- <!---->
- <exec executable="dot">
- <arg line="-Tpng -Grankdir=LR -Nshape=box -Nfontsize=9 -Nwidth=0.3 -Nheight=0.2 ${dependency.external.grph} -O"/>
- </exec>
-
- </target>
-
- <!-- Private: Convert db file -->
- <target name="dependency-db-convert" depends="database">
- <copy file="${database.file}" tofile="${database.file}.parsed" overwrite="true">
- <filterchain>
- <expandproperties/>
- </filterchain>
- </copy>
- </target>
-
- <!-- Generates a dependancy diagram of log files -->
- <target name="dependency-logs">
- <property name="dependency.external.grph" value="${helium.build.dir}/doc/images/dependencies_log.grph"/>
-
- <antcall target="dependency-db-convert" inheritAll="false">
- <param name="build.drive" value="build.drive"/>
- <param name="build.id" value="build.id"/>
- <param name="build.log.dir" value="/output/logs"/>
- </antcall>
-
- <hlm:python>
-import os
-import dependancygraph
-
-dependancygraph.findLogFiles(r'${database.file}.parsed', r'${dependency.external.grph}')
- </hlm:python>
- <!---->
- <exec executable="dot">
- <arg line="-Tpng -Grankdir=LR -Nshape=box -Nfontsize=9 -Nwidth=0.3 -Nheight=0.2 ${dependency.external.grph} -O"/>
- </exec>
-
- </target>
-
-
- <!-- Creates user flow diagram -->
- <target name="helium-user-graph">
- <mkdir dir="${helium.build.dir}/doc/api"/>
- <fmpp sourcefile="${helium.doc.dir}/src/user-graph.dot.ftl" outputfile="${helium.build.dir}/temp/doc/user-graph.dot">
- <data expandProperties="yes">
- ant: antProperties()
- </data>
- </fmpp>
- <for param="dot.file">
- <fileset dir="${helium.build.dir}/temp/doc" includes="user-graph.dot"/>
- <sequential>
- <echo>Processing dot file: @{dot.file}</echo>
- <exec executable="dot" dir="${helium.build.dir}/temp/doc/">
- <arg line="-Tcmap @{dot.file} -O"/>
- </exec>
- <exec executable="dot" dir="${helium.build.dir}/doc/api">
- <arg line="-Tpng @{dot.file} -O"/>
- </exec>
- </sequential>
- </for>
- <move todir="${helium.build.dir}/doc/images" overwrite="true">
- <fileset dir="${helium.build.dir}/temp/doc" includes="user-graph.dot.png"/>
- </move>
- </target>
+ <!-- generate all the user documentation for helium -->
+ <target name="docs" depends="clean-docs,apidocs,textdocs"/>
</project>