scons.manuals

1 ############################################################################### 2 # # 3 # Copyright (C) 2006 Edward d'Auvergne # 4 # # 5 # This file is part of the program relax. # 6 # # 7 # relax is free software; you can redistribute it and/or modify # 8 # it under the terms of the GNU General Public License as published by # 9 # the Free Software Foundation; either version 2 of the License, or # 10 # (at your option) any later version. # 11 # # 12 # relax is distributed in the hope that it will be useful, # 13 # but WITHOUT ANY WARRANTY; without even the implied warranty of # 14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # 15 # GNU General Public License for more details. # 16 # # 17 # You should have received a copy of the GNU General Public License # 18 # along with relax; if not, write to the Free Software # 19 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # 20 # # 21 ############################################################################### 22 23 24 # Import statements. 25 from glob import glob 26 import platform 27 from os import F_OK, access, chdir, getcwd, path, remove, sep, system 28 from shutil import move 29 import sys 30 31 from version import version 32 33 34

35 -def clean_manual_files(target, source, env):

36 """Builder action for removing the temporary manual files.""" 37 38 # Print out. 39 print 40 print "##########################################" 41 print "# Cleaning up the temporary manual files #" 42 print "##########################################\n\n" 43 44 # File list to remove. 45 files = ["relax.bbl", 46 "relax.blg", 47 "relax.dvi", 48 "relax.idx", 49 "relax.ilg", 50 "relax.ind", 51 "relax.lof", 52 "relax.log", 53 "relax.lot", 54 "relax.out", 55 "relax.toc"] 56 57 # Add the LaTeX directory. 58 for i in xrange(len(files)): 59 files[i] = path.join(env['LATEX_DIR'], files[i]) 60 61 # LaTeX auxillary files. 62 for file in glob(env['LATEX_DIR'] + '*.aux'): 63 files.append(file) 64 65 # Remove the files. 66 for file in files: 67 try: 68 remove(file) 69 except OSError, message: 70 # The file does not exist. 71 if message.errno == 2: 72 pass 73 74 # All other errors. 75 else: 76 raise 77 else: 78 print "Removing the file " + `file` + "." 79 80 # Final print out. 81 print "\n\n\n"

82 83

84 -def compile_api_manual_html(target, source, env):

85 """Builder action for compiling the API documentation manual (HTML version) using Epydoc.""" 86 87 # Print out. 88 print 89 print "#####################################################" 90 print "# Compiling API documentation manual (HTML version) #" 91 print "#####################################################\n\n" 92 93 94 # Set up the Epydoc configuration (adapted from http://epydoc.sourceforge.net/configfile.html). 95 ############################################################################################### 96 97 # modules 98 # The list of objects to document. 99 modules = ['relax', 100 '*.py', 101 'docs/*.py', 102 'docs/latex/*.py', 103 'dx/*.py', 104 'generic_fns/*.py', 105 'maths_fns/*.py', 106 'prompt/*.py', 107 'specific_fns/*.py', 108 'test_suite/*.py', 109 'sconstruct', 110 'scons/*.py'] 111 112 # output 113 # The type of output that should be generated. Should be one 114 # of: html, text, latex, dvi, ps, pdf. 115 output = 'html' 116 117 # target 118 # The path to the output directory. May be relative or absolute. 119 target = 'docs/api' 120 121 # docformat 122 # The default markup language for docstrings, for modules that do 123 # not define __docformat__. 124 docformat = 'epytext' 125 126 # css 127 # The CSS stylesheet for HTML output. Can be the name of a builtin 128 # stylesheet, or the name of a file. 129 css = 'white' 130 131 # name 132 # The documented project's name. 133 name = 'relax' 134 135 # url 136 # The documented project's URL. 137 url = 'http://nmr-relax.com' 138 139 # link 140 # HTML code for the project link in the navigation bar. If left 141 # unspecified, the project link will be generated based on the 142 # project's name and URL. 143 #link = '<a href="http://nmr-relax.com">relax</a>' 144 145 # top 146 # The "top" page for the documentation. Can be a URL, the name 147 # of a module or class, or one of the special names "trees.html", 148 # "indices.html", or "help.html" 149 # top = 'os.path' 150 151 # help 152 # An alternative help file. The named file should contain the 153 # body of an HTML file; navigation bars will be added to it. 154 # help = 'my_helpfile.html' 155 156 # frames 157 # Whether or not to include a frames-based table of contents. 158 frames = 1 159 160 # private 161 # Whether or not to inclue private variables. (Even if included, 162 # private variables will be hidden by default.) 163 private = 1 164 165 # imports 166 # Whether or not to list each module's imports. 167 imports = 1 168 169 # verbosity 170 # An integer indicating how verbose epydoc should be. The default 171 # value is 0; negative values will supress warnings and errors; 172 # positive values will give more verbose output. 173 verbosity = 1 174 175 # parse 176 # Whether or not parsing should be used to examine objects. 177 parse = 1 178 179 # introspect 180 # Whether or not introspection should be used to examine objects. 181 introspect = 1 182 183 # graph 184 # The list of graph types that should be automatically included 185 # in the output. Graphs are generated using the Graphviz "dot" 186 # executable. Graph types include: "classtree", "callgraph", 187 # "umlclass". Use "all" to include all graph types 188 graph = 'all' 189 190 # dotpath 191 # The path to the Graphviz "dot" executable, used to generate 192 # graphs. 193 #dotpath = '/usr/local/bin/dot' 194 195 # sourcecode 196 # Whether or not to include syntax highlighted source code in 197 # the output (HTML only). 198 sourcecode = 1 199 200 # pstat 201 # The name of one or more pstat files (generated by the profile 202 # or hotshot module). These are used to generate call graphs. 203 #pstat = 'profile.out' 204 205 # separate-classes 206 # Whether each class should be listed in its own section when 207 # generating LaTeX or PDF output. 208 #separate-classes = 0 209 210 211 212 # Construct the command line string. 213 #################################### 214 215 # Program name, output, target, docformat, css, name, and url. 216 epydoc_cmd = 'epydoc' + ' --' + output + ' -o ' + target + ' --docformat ' + docformat + ' --css ' + css + ' --name ' + name + ' --url ' + url 217 218 # Frames. 219 if frames: 220 epydoc_cmd = epydoc_cmd + ' --show-frames' 221 else: 222 epydoc_cmd = epydoc_cmd + ' --no-frames' 223 224 # Private variables. 225 if private: 226 epydoc_cmd = epydoc_cmd + ' --show-private' 227 else: 228 epydoc_cmd = epydoc_cmd + ' --no-private' 229 230 # Module imports. 231 if imports: 232 epydoc_cmd = epydoc_cmd + ' --show-imports' 233 else: 234 epydoc_cmd = epydoc_cmd + ' --no-imports' 235 236 # Verbosity. 237 if verbosity > 0: 238 for i in range(verbosity): 239 epydoc_cmd = epydoc_cmd + ' -v' 240 elif verbosity < 0: 241 for i in range(-verbosity): 242 epydoc_cmd = epydoc_cmd + ' -q' 243 244 # Parsing and introspection. 245 if parse and not introspect: 246 epydoc_cmd = epydoc_cmd + ' --parse-only' 247 elif not parse and introspect: 248 epydoc_cmd = epydoc_cmd + ' --introspect-only' 249 250 # Graph. 251 epydoc_cmd = epydoc_cmd + ' --graph ' + graph 252 253 # Sourcecode. 254 if sourcecode: 255 epydoc_cmd = epydoc_cmd + ' --show-sourcecode' 256 else: 257 epydoc_cmd = epydoc_cmd + ' --no-sourcecode' 258 259 # Modules. 260 for module in modules: 261 epydoc_cmd = epydoc_cmd + ' ' + module 262 263 264 # Execute Epydoc. 265 ################# 266 267 # Print out. 268 print "Running the command:\n$ " + epydoc_cmd + "\n\n\n" 269 270 # System call. 271 system(epydoc_cmd) 272 273 274 275 # Modify the CSS file. 276 ###################### 277 278 # Open the file. 279 css_file = open(target + '/epydoc.css', 'a') 280 281 # Header. 282 css_file.write("\n\n\n\n/* Edward */\n\n") 283 284 # Append the new link style to the end. 285 css_file.write("a { text-decoration:none; color:#0017aa; font-weight:normal; }\n") 286 css_file.write("a:hover { color:#316fff; }\n") 287 288 # Close the file. 289 css_file.close() 290 291 # Final print out. 292 print "\n\n\n"

293 294

295 -def compile_user_manual_html(target, source, env):

296 """Builder action for compiling the user manual (HTML version) from the LaTeX sources.""" 297 298 # Print out. 299 print 300 print "############################################" 301 print "# Compiling the user manual (HTML version) #" 302 print "############################################\n\n" 303 304 # Go to the LaTeX directory. 305 base_dir = getcwd() 306 chdir(env['LATEX_DIR']) 307 308 # Run the latex2html command. 309 print "Running the command:\n$ latex2html -split +3 -html_version 4.0 -dir " + path.pardir + path.sep + "html relax.tex\n\n\n" 310 system("latex2html -split +3 -html_version 4.0 -dir " + path.pardir + path.sep + "html relax.tex") 311 312 # Return to the base directory. 313 chdir(base_dir) 314 315 # Final print out. 316 print "\n\n\n"

317 318

319 -def compile_user_manual_pdf(target, source, env):

320 """Builder action for compiling the user manual (PDF version) from the LaTeX sources.""" 321 322 # Print out. 323 print 324 print "###########################################" 325 print "# Compiling the user manual (PDF version) #" 326 print "###########################################\n\n" 327 328 # Go to the LaTeX directory. 329 base_dir = getcwd() 330 chdir(env['LATEX_DIR']) 331 332 print "\n\n\n <<< LaTeX (first round) >>>\n\n\n" 333 system('latex relax') 334 335 print "\n\n\n <<< Bibtex >>>\n\n\n" 336 system('bibtex relax') 337 338 print "\n\n\n <<< Makeindex >>>\n\n\n" 339 system('makeindex relax') 340 341 print "\n\n\n <<< LaTeX (second round) >>>\n\n\n" 342 system('latex relax') 343 344 print "\n\n\n <<< LaTeX (third round) >>>\n\n\n" 345 system('latex relax') 346 347 print "\n\n\n <<< LaTeX (fourth round) >>>\n\n\n" 348 system('latex relax') 349 350 print "\n\n\n <<< dvips >>>\n\n\n" 351 system('dvips -o relax.ps relax.dvi') 352 353 print "\n\n\n <<< ps2pdf >>>\n\n\n" 354 if env['SYSTEM'] == 'Windows': 355 # According to the Ghostscript documentation, "When passing options to ghostcript through a batch 356 # file wrapper such as ps2pdf.bat you need to substitute '#' for '=' as the separator between options 357 # and their arguments." 358 assign = '#' 359 else: 360 assign = '=' 361 system('ps2pdf -dAutoFilterColorImages' + assign + 'false -dAutoFilterGrayImages' + assign + 'false -dColorImageFilter' + assign + '/FlateEncode -dColorImageFilter' + assign + '/FlateEncode -dGrayImageFilter' + assign + '/FlateEncode -dMonoImageFilter' + assign + '/FlateEncode -dPDFSETTINGS' + assign + '/prepress relax.ps relax.pdf') 362 363 print "\n\n\n <<< Removing the PS file and shifting the PDF down a directory >>>\n\n\n" 364 if access('relax.ps', F_OK): 365 remove('relax.ps') 366 if access('relax.pdf', F_OK): 367 move('relax.pdf', path.pardir) 368 369 # Return to the base directory. 370 chdir(base_dir) 371 372 # Final print out. 373 print "\n\n\n"

374 375

376 -def fetch_docstrings(target, source, env):

377 """Builder action for fetching the relax user function docstrings.""" 378 379 # Print out. 380 print 381 print "###############################################" 382 print "# Fetching the relax user function docstrings #" 383 print "###############################################\n\n" 384 385 # Import the fetch_docstrings module (needs to be done here so that Sconstruct doesn't need to load the entire program each time). 386 sys.path.append(getcwd()) 387 from docs.latex.fetch_docstrings import Fetch_docstrings 388 389 # Get the docstrings. 390 Fetch_docstrings(env['LATEX_DIR'] + sep + 'docstring.tex') 391 392 # Delete the Fetch_docstrings class. This allows the loaded dll files to be deleted through python on MS Windows. 393 del Fetch_docstrings 394 395 # Final print out. 396 print "\n\n\n"

397 398

399 -def version_file(target, source, env):

400 """Builder action for creating the LaTeX relax version file.""" 401 402 # Print out. 403 print 404 print "################################################" 405 print "# Creating the LaTeX relax version number file #" 406 print "################################################" 407 408 # Place the program version number into a LaTeX file. 409 file = open(env['LATEX_DIR'] + sep + 'relax_version.tex', 'w') 410 file.write("Version " + version + '\n') 411 file.close() 412 413 # Final print out. 414 print "\n\n\n"

415

Source Code for Module scons.manuals