|
1 <?xml version="1.0" encoding="UTF-8"?> |
|
2 <!-- |
|
3 ============================================================================ |
|
4 Name : docs.ant.xml |
|
5 Part of : Helium |
|
6 |
|
7 Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
8 All rights reserved. |
|
9 This component and the accompanying materials are made available |
|
10 under the terms of the License "Eclipse Public License v1.0" |
|
11 which accompanies this distribution, and is available |
|
12 at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
13 |
|
14 Initial Contributors: |
|
15 Nokia Corporation - initial contribution. |
|
16 |
|
17 Contributors: |
|
18 |
|
19 Description: |
|
20 |
|
21 ============================================================================ |
|
22 --> |
|
23 <!--* @package framework --> |
|
24 <project name="internal.docs" xmlns:hlm="http://www.nokia.com/helium" xmlns:ivy="antlib:org.apache.ivy.ant"> |
|
25 <description> |
|
26 Documentation generation targets. |
|
27 </description> |
|
28 |
|
29 <!-- Location of documentation source. |
|
30 @type string |
|
31 @scope public |
|
32 --> |
|
33 <property name="doc.src.dir" location="${basedir}/doc" /> |
|
34 |
|
35 <!-- The location where the docs will be built. |
|
36 @type string |
|
37 @scope private --> |
|
38 <property name="docs.build.dir" location="${basedir}/build/doc" /> |
|
39 |
|
40 <fileset id="python.library.files" dir="${helium.dir}"> |
|
41 <include name="extensions/nokia/tools/common/python/lib/**/*.py"/> |
|
42 <include name="tools/common/python/lib/**/*.py"/> |
|
43 <include name="external/helium-antlib/python/**/*.py"/> |
|
44 <include name="extensions/nokia/external/helium-nokia-antlib/python/**/*.py"/> |
|
45 </fileset> |
|
46 |
|
47 <fileset id="static.doc.files" dir="${helium.dir}/doc/src"> |
|
48 <include name="conf.py"/> |
|
49 <include name=".static"/> |
|
50 <include name=".templates/**"/> |
|
51 <include name="*.jpg"/> |
|
52 <include name="*.css"/> |
|
53 </fileset> |
|
54 |
|
55 |
|
56 <!-- Cleans the Helium API documentation. --> |
|
57 <target name="clean-helium-apidocs"> |
|
58 <delete dir="${docs.build.dir}/api/helium"/> |
|
59 <delete dir="${docs.build.dir}/temp/doc/api/helium"/> |
|
60 </target> |
|
61 |
|
62 |
|
63 <!-- Creates images of the dependencies for all Ant targets. |
|
64 |
|
65 This includes creating a cmap file that is included in the HTML document, |
|
66 so the boxes in the image are linked to their targets. --> |
|
67 <target name="helium-api-dependency-images"> |
|
68 <mkdir dir="${docs.build.dir}/api/helium"/> |
|
69 <fmpp sourceRoot="${helium.dir}/doc/src/api" includes="*.dot.ftl" outputRoot="${docs.build.dir}/temp/doc/api/helium" |
|
70 replaceExtension="dot.ftl, dot"> |
|
71 <data expandProperties="yes"> |
|
72 doc: xml(${database.file}) |
|
73 </data> |
|
74 </fmpp> |
|
75 <for param="dot.file" parallel="true" threadCount="${number.of.threads}"> |
|
76 <fileset dir="${docs.build.dir}/temp/doc/api/helium" includes="*.dot"/> |
|
77 <sequential> |
|
78 <echo>Processing dot file: @{dot.file}</echo> |
|
79 <exec executable="dot" dir="${docs.build.dir}/temp/doc/api/helium"> |
|
80 <arg line="-Tcmap @{dot.file} -O"/> |
|
81 </exec> |
|
82 <exec executable="dot" dir="${docs.build.dir}/api"> |
|
83 <arg line="-Tpng @{dot.file} -O"/> |
|
84 </exec> |
|
85 </sequential> |
|
86 </for> |
|
87 <move todir="${docs.build.dir}/api/helium" overwrite="true"> |
|
88 <fileset dir="${docs.build.dir}/temp/doc/api/helium" includes="*.dot.png"/> |
|
89 </move> |
|
90 </target> |
|
91 |
|
92 |
|
93 <!-- Builds the HTML files for the Helium API documentation. --> |
|
94 <target name="helium-api-html-docs"> |
|
95 <mkdir dir="${docs.build.dir}/api/helium"/> |
|
96 <copy todir="${docs.build.dir}/temp/doc/api/helium" overwrite="true"> |
|
97 <fileset dir="${helium.dir}/doc/src/api"/> |
|
98 </copy> |
|
99 <fmpp sourceRoot="${docs.build.dir}/temp/doc/api/helium" excludes="*.dot.png,*.dot.ftl,**/*.dot,**/*.cmap,*.bak" |
|
100 outputRoot="${docs.build.dir}/api/helium" |
|
101 replaceExtension="html.ftl, html"> |
|
102 <data expandProperties="yes"> |
|
103 ant: antProperties() |
|
104 doc: xml(${database.file}) |
|
105 </data> |
|
106 </fmpp> |
|
107 </target> |
|
108 |
|
109 |
|
110 <!-- Builds the Helium API documentation. --> |
|
111 <target name="helium-apidocs" depends="clean-helium-apidocs,database, |
|
112 helium-api-dependency-images,helium-api-html-docs"/> |
|
113 |
|
114 |
|
115 <!-- Generate search index for apis --> |
|
116 <target name="apidocs-search"> |
|
117 <hlm:python> |
|
118 import html2rest |
|
119 import os |
|
120 import codecs |
|
121 #import traceback |
|
122 for root, dirs, files in os.walk(r'${docs.build.dir}/api', topdown=False): |
|
123 for fname in files: |
|
124 if '.html' in fname: |
|
125 filename = os.path.abspath(os.path.join(root, fname)) |
|
126 rstfilename = filename.replace('.html', '.rst') |
|
127 try: |
|
128 out = open(rstfilename, 'w') |
|
129 html2rest.html2rest(html2rest.readsoup(filename), out) |
|
130 except: |
|
131 #traceback.print_exc() |
|
132 print filename + ' failed to be converted to rst' |
|
133 finally: |
|
134 out.close() |
|
135 |
|
136 try: |
|
137 rstfile = codecs.open(rstfilename, 'r', 'utf8') |
|
138 rstfile.read() |
|
139 except: |
|
140 print rstfilename + ' has invalid unicode' |
|
141 rstfile.close() |
|
142 os.remove(rstfilename) |
|
143 </hlm:python> |
|
144 |
|
145 <move todir="${docs.build.dir}/temp_search/doc" overwrite="true"> |
|
146 <fileset dir="${docs.build.dir}/api"> |
|
147 <include name="**/*.rst"/> |
|
148 </fileset> |
|
149 </move> |
|
150 |
|
151 <move todir="${docs.build.dir}/api_backup" overwrite="true"> |
|
152 <fileset dir="${docs.build.dir}/api"/> |
|
153 </move> |
|
154 |
|
155 <copy file="${helium.dir}/doc/src/api/apisearchindex.rst" tofile="${docs.build.dir}/temp_search/doc/index.rst"/> |
|
156 |
|
157 <copy todir="${docs.build.dir}/temp_search/doc"> |
|
158 <fileset refid="static.doc.files"/> |
|
159 </copy> |
|
160 |
|
161 <hlm:rstMacro src="${docs.build.dir}/temp_search/doc" output="${docs.build.dir}/api"/> |
|
162 |
|
163 <move todir="${docs.build.dir}/api" overwrite="true"> |
|
164 <fileset dir="${docs.build.dir}/api_backup"/> |
|
165 </move> |
|
166 </target> |
|
167 |
|
168 |
|
169 <!-- Generate API documentation from the source code. --> |
|
170 <target name="apidocs" depends="helium-apidocs,apidocs-search"/> |
|
171 |
|
172 |
|
173 <!-- Macro to generate HTML docs from rst. --> |
|
174 <macrodef name="rstMacro" uri="http://www.nokia.com/helium"> |
|
175 <attribute name="version" default="${helium.version}"/> |
|
176 <attribute name="src" default="${docs.build.dir}/temp/doc"/> |
|
177 <attribute name="output" default="${docs.build.dir}"/> |
|
178 <sequential> |
|
179 <property name="sphinx.lib.dir" location="${helium.dir}/external/python/lib/common/Sphinx-0.5.1-py2.5.egg/sphinx" /> |
|
180 <if> |
|
181 <available file="${nokia.python.tools}/sphinxfixsearch.diff"/> |
|
182 <then> |
|
183 <patch patchfile="${nokia.python.tools}/sphinxfixsearch.diff" originalfile="${sphinx.lib.dir}/search.py"/> |
|
184 </then> |
|
185 </if> |
|
186 <if> |
|
187 <resourcecount when="greater" count="0"> |
|
188 <fileset dir="@{src}" includes="**/*.rst"/> |
|
189 </resourcecount> |
|
190 <then> |
|
191 <exec executable="python" failonerror="true"> |
|
192 <arg file="${python.dir}/common/sphinx-build.py"/> |
|
193 <arg value="-b" /> |
|
194 <arg value="html" /> |
|
195 <arg value="-D" /> |
|
196 <arg value="version=@{version}" /> |
|
197 <arg value="-D" /> |
|
198 <arg value="release=@{version}" /> |
|
199 <arg file="@{src}" /> |
|
200 <arg file="@{output}" /> |
|
201 </exec> |
|
202 </then> |
|
203 </if> |
|
204 <if> |
|
205 <available file="${nokia.python.tools}/sphinxfixsearch.diff"/> |
|
206 <then> |
|
207 <patch reverse="true" patchfile="${nokia.python.tools}/sphinxfixsearch.diff" originalfile="${sphinx.lib.dir}/search.py"/> |
|
208 </then> |
|
209 </if> |
|
210 </sequential> |
|
211 </macrodef> |
|
212 |
|
213 |
|
214 <!-- Generate rst files for docs --> |
|
215 <target name="prep-textdocs"> |
|
216 <echo>Building docs into ${docs.build.dir}.</echo> |
|
217 <mkdir dir="${docs.build.dir}/images"/> |
|
218 |
|
219 <delete dir="${docs.build.dir}/.doctrees"/> |
|
220 <delete file="${docs.build.dir}/searchindex.json"/> |
|
221 |
|
222 <copy todir="${docs.build.dir}/images" failonerror="false"> |
|
223 <fileset dir="${doc.src.dir}/images"/> |
|
224 </copy> |
|
225 |
|
226 <!-- Temporarily copy the image directory so that doc generation will complete happily.--> |
|
227 <copy todir="${docs.build.dir}/temp/doc/images" failonerror="false"> |
|
228 <fileset dir="${docs.build.dir}/images"/> |
|
229 </copy> |
|
230 |
|
231 <if> |
|
232 <available file="${doc.src.dir}/src"/> |
|
233 <then> |
|
234 <copy todir="${docs.build.dir}/temp/doc"> |
|
235 <fileset dir="${doc.src.dir}/src"> |
|
236 <include name="**/*.rst"/> |
|
237 <include name="**/*.css"/> |
|
238 <include name="**/*.jpg"/> |
|
239 <include name="**/*.dot"/> |
|
240 </fileset> |
|
241 </copy> |
|
242 |
|
243 <!--<fileset id="internal.ref.minibuilds" dir="${docs.build.dir}/temp/doc/minibuilds" includes="*/**/index.rst"/>--> |
|
244 <fmpp sourceRoot="${doc.src.dir}/src" |
|
245 outputRoot="${docs.build.dir}/temp/doc" includes="*.rst.ftl" removeExtensions="ftl" excludes="api_changes.rst.ftl,minibuilds.rst.ftl"> |
|
246 <data expandProperties="yes"> |
|
247 ant: antProperties() |
|
248 project: antProject() |
|
249 </data> |
|
250 </fmpp> |
|
251 </then> |
|
252 </if> |
|
253 |
|
254 <!-- Copy static content files from Helium --> |
|
255 <copy todir="${docs.build.dir}/temp/doc"> |
|
256 <fileset refid="static.doc.files"/> |
|
257 </copy> |
|
258 |
|
259 <for param="dot.file"> |
|
260 <fileset dir="${docs.build.dir}/temp/doc" includes="manual/*.dot"/> |
|
261 <sequential> |
|
262 <echo>Building dot file: @{dot.file}</echo> |
|
263 <exec executable="dot"> |
|
264 <arg line="-Tpng @{dot.file} -O"/> |
|
265 </exec> |
|
266 </sequential> |
|
267 </for> |
|
268 </target> |
|
269 |
|
270 |
|
271 <!-- Generate HTML documentation from .rst documents with Sphinx. |
|
272 |
|
273 All doc .rst files should be generated or copied into build/temp/doc before being processed into HTML. |
|
274 --> |
|
275 <target name="textdocs" depends="prep-textdocs"> |
|
276 <hlm:rstMacro /> |
|
277 |
|
278 <copy file="${database.file}" todir="${docs.build.dir}"/> |
|
279 <copy file="${docs.build.dir}/temp/doc/default.css" todir="${docs.build.dir}/_static" overwrite="true" failonerror="true"/> |
|
280 <copy file="${docs.build.dir}/temp/doc/helium_pallot_small.jpg" todir="${docs.build.dir}/_static" overwrite="true"/> |
|
281 <copy todir="${docs.build.dir}" overwrite="true"> |
|
282 <fileset dir="${doc.src.dir}/src"> |
|
283 <include name="**/*.zip"/> |
|
284 </fileset> |
|
285 </copy> |
|
286 </target> |
|
287 |
|
288 |
|
289 <!-- Clean old build/doc dir. --> |
|
290 <target name="clean-docs"> |
|
291 <delete dir="${docs.build.dir}"/> |
|
292 </target> |
|
293 |
|
294 |
|
295 <!-- generate all the user documentation for helium --> |
|
296 <target name="docs" depends="clean-docs,apidocs,textdocs"/> |
|
297 |
|
298 </project> |