scons.manuals

1 ############################################################################### 2 # # 3 # Copyright (C) 2006-2012 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 # Module docstring. 24 """SCons targets for building the relax manuals.""" 25 26 # Python module imports. 27 from glob import glob 28 from os import F_OK, access, chdir, getcwd, listdir, path, remove, rename, sep, system 29 from re import search 30 import sys 31 32 # relax module imports. 33 from status import Status; status = Status() 34 from version import version 35 36

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

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

84 85

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

87 """Builder action for compiling the API documentation manual (HTML version) using Epydoc.""" 88 89 # Print out. 90 print('') 91 print("#####################################################") 92 print("# Compiling API documentation manual (HTML version) #") 93 print("#####################################################\n\n") 94 95 96 # Set up the Epydoc configuration (adapted from http://epydoc.sourceforge.net/configfile.html). 97 ############################################################################################### 98 99 # exclude 100 # The list of objects to exclude. 101 exclude = [ 102 'extern', 103 'graphics', 104 'minfx.scipy_subset', 105 'multi.test_implementation', 106 'multi.test_implementation2', 107 'sample_scripts', 108 'scripts' 109 ] 110 111 # output 112 # The type of output that should be generated. Should be one 113 # of: html, text, latex, dvi, ps, pdf. 114 output = 'html' 115 116 # target 117 # The path to the output directory. May be relative or absolute. 118 target = 'docs'+sep+'api' 119 120 # docformat 121 # The default markup language for docstrings, for modules that do 122 # not define __docformat__. 123 docformat = 'epytext' 124 125 # css 126 # The CSS stylesheet for HTML output. Can be the name of a builtin 127 # stylesheet, or the name of a file. 128 css = 'white' 129 130 # name 131 # The documented project's name. 132 name = 'relax' 133 134 # url 135 # The documented project's URL. 136 url = 'http://www.nmr-relax.com' 137 138 # link 139 # HTML code for the project link in the navigation bar. If left 140 # unspecified, the project link will be generated based on the 141 # project's name and URL. 142 #link = '<a href="/">relax</a>' 143 144 # top 145 # The "top" page for the documentation. Can be a URL, the name 146 # of a module or class, or one of the special names "trees.html", 147 # "indices.html", or "help.html" 148 # top = 'os.path' 149 150 # help 151 # An alternative help file. The named file should contain the 152 # body of an HTML file; navigation bars will be added to it. 153 # help = 'my_helpfile.html' 154 155 # frames 156 # Whether or not to include a frames-based table of contents. 157 frames = 1 158 159 # private 160 # Whether or not to inclue private variables. (Even if included, 161 # private variables will be hidden by default.) 162 private = 1 163 164 # imports 165 # Whether or not to list each module's imports. 166 imports = 1 167 168 # verbosity 169 # An integer indicating how verbose epydoc should be. The default 170 # value is 0; negative values will supress warnings and errors; 171 # positive values will give more verbose output. 172 verbosity = 1 173 174 # parse 175 # Whether or not parsing should be used to examine objects. 176 parse = 1 177 178 # introspect 179 # Whether or not introspection should be used to examine objects. 180 introspect = 1 181 182 # graph 183 # The list of graph types that should be automatically included 184 # in the output. Graphs are generated using the Graphviz "dot" 185 # executable. Graph types include: "classtree", "callgraph", 186 # "umlclass". Use "all" to include all graph types 187 graph = 'all' 188 189 # dotpath 190 # The path to the Graphviz "dot" executable, used to generate 191 # graphs. 192 #dotpath = '/usr/local/bin/dot' 193 194 # sourcecode 195 # Whether or not to include syntax highlighted source code in 196 # the output (HTML only). 197 sourcecode = 1 198 199 # pstat 200 # The name of one or more pstat files (generated by the profile 201 # or hotshot module). These are used to generate call graphs. 202 #pstat = 'profile.out' 203 204 # separate-classes 205 # Whether each class should be listed in its own section when 206 # generating LaTeX or PDF output. 207 #separate-classes = 0 208 209 210 211 # Construct the command line string. 212 #################################### 213 214 # Program name, output, target, docformat, css, name, and url. 215 epydoc_cmd = 'epydoc' + ' --' + output + ' -o ' + target + ' --docformat ' + docformat + ' --css ' + css + ' --name ' + name + ' --url ' + url 216 217 # Frames. 218 if frames: 219 epydoc_cmd = epydoc_cmd + ' --show-frames' 220 else: 221 epydoc_cmd = epydoc_cmd + ' --no-frames' 222 223 # Private variables. 224 if private: 225 epydoc_cmd = epydoc_cmd + ' --show-private' 226 else: 227 epydoc_cmd = epydoc_cmd + ' --no-private' 228 229 # Module imports. 230 if imports: 231 epydoc_cmd = epydoc_cmd + ' --show-imports' 232 else: 233 epydoc_cmd = epydoc_cmd + ' --no-imports' 234 235 # Verbosity. 236 if verbosity > 0: 237 for i in range(verbosity): 238 epydoc_cmd = epydoc_cmd + ' -v' 239 elif verbosity < 0: 240 for i in range(-verbosity): 241 epydoc_cmd = epydoc_cmd + ' -q' 242 243 # Parsing and introspection. 244 if parse and not introspect: 245 epydoc_cmd = epydoc_cmd + ' --parse-only' 246 elif not parse and introspect: 247 epydoc_cmd = epydoc_cmd + ' --introspect-only' 248 249 # Graph. 250 epydoc_cmd = epydoc_cmd + ' --graph ' + graph 251 252 # Sourcecode. 253 if sourcecode: 254 epydoc_cmd = epydoc_cmd + ' --show-sourcecode' 255 else: 256 epydoc_cmd = epydoc_cmd + ' --no-sourcecode' 257 258 # Excluded modules. 259 for name in exclude: 260 epydoc_cmd = epydoc_cmd + ' --exclude=' + name 261 262 # All the files of the current directory. 263 blacklist = ['README', 'relax.bat', 'relax_gui_mode.py'] 264 files = listdir(getcwd()) 265 for file in files: 266 # Blacklisted. 267 if file in blacklist: 268 continue 269 270 # Otherwise add it. 271 epydoc_cmd = "%s %s" % (epydoc_cmd, file) 272 273 274 # Execute Epydoc. 275 ################# 276 277 # Print out. 278 print(("Running the command:\n$ " + epydoc_cmd + "\n\n\n")) 279 280 # System call. 281 system(epydoc_cmd) 282 283 284 285 # Modify the CSS file. 286 ###################### 287 288 # Open the file. 289 css_file = open(target + sep+'epydoc.css', 'a') 290 291 # Header. 292 css_file.write("\n\n\n\n/* Edward */\n\n") 293 294 # Append the new link style to the end. 295 css_file.write("a { text-decoration:none; color:#0017aa; font-weight:normal; }\n") 296 css_file.write("a:hover { color:#316fff; }\n") 297 298 # Close the file. 299 css_file.close() 300 301 302 # Modify all HTML files. 303 ######################## 304 305 # Print out. 306 print("\n\nModifying the <head> tag of all HTML files.\n") 307 308 # The additional head tags. 309 head_lines = [] 310 311 # The Google analytics JS. 312 file = open(status.install_path + sep + 'scripts' + sep + 'google_analytics.js') 313 for line in file.readlines(): 314 head_lines.append(line) 315 file.close() 316 317 # Loop over the files. 318 for file_name in listdir(status.install_path + sep + 'docs' + sep + 'api'): 319 # The full path. 320 full_path = status.install_path + sep + 'docs' + sep + 'api' + sep + file_name 321 322 # Skip all non-html files. 323 if not search('.html$', full_path): 324 continue 325 326 # Print out. 327 print(full_path) 328 329 # Open the file and read the data. 330 file = open(full_path) 331 lines = file.readlines() 332 file.close() 333 334 # Modify the original file. 335 file = open(full_path, 'w') 336 337 # Loop over the lines. 338 found = False 339 for i in range(len(lines)): 340 # Find the position of </head>. 341 if not found and search('</head>', lines[i]): 342 # Append the head lines. 343 for j in range(len(head_lines)): 344 file.write(head_lines[j]) 345 346 # The found flag. 347 found = True 348 349 # Append the old line. 350 file.write(lines[i]) 351 352 # Close the file. 353 file.close() 354 355 # Final print out. 356 print("\n\n\n")

357 358

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

360 """Builder action for compiling the user manual (HTML version) from the LaTeX sources.""" 361 362 # Make the PDF manual to generate the aux files. 363 compile_user_manual_pdf(target, source, env, convert=False) 364 365 # Print out. 366 print('') 367 print("############################################") 368 print("# Compiling the user manual (HTML version) #") 369 print("############################################\n\n") 370 371 # Go to the LaTeX directory. 372 base_dir = getcwd() 373 chdir(env['LATEX_DIR']) 374 375 # The target directory. 376 dir = path.pardir + path.sep + "html" 377 378 # Run the latex2html command. 379 cmd = "latex2html -dir %s relax.tex" % (dir) 380 print("Running the command:\n$ %s\n\n\n" % cmd) 381 system(cmd) 382 383 # Create the proper index.html file. 384 cmd = "cp -vp %s%srelax_user_manual.html %s%s index.html" % (dir, path.sep, dir, path.sep) 385 print("Running the command:\n$ %s\n\n\n" % cmd) 386 system(cmd) 387 388 # Return to the base directory. 389 chdir(base_dir) 390 391 # Final print out. 392 print("\n\n\n")

393 394

395 -def compile_user_manual_pdf(target, source, env, convert=True):

396 """Builder action for compiling the user manual (PDF version) from the LaTeX sources.""" 397 398 # Print out. 399 print('') 400 print("###########################################") 401 print("# Compiling the user manual (PDF version) #") 402 print("###########################################\n\n") 403 404 # Go to the LaTeX directory. 405 base_dir = getcwd() 406 chdir(env['LATEX_DIR']) 407 408 print("\n\n\n <<< LaTeX (first round) >>>\n\n\n") 409 system('latex relax') 410 411 print("\n\n\n <<< Bibtex >>>\n\n\n") 412 system('bibtex relax') 413 414 print("\n\n\n <<< Makeindex >>>\n\n\n") 415 system('makeindex relax') 416 417 print("\n\n\n <<< LaTeX (second round) >>>\n\n\n") 418 system('latex relax') 419 420 print("\n\n\n <<< LaTeX (third round) >>>\n\n\n") 421 system('latex relax') 422 423 print("\n\n\n <<< LaTeX (fourth round) >>>\n\n\n") 424 system('latex relax') 425 426 # Skip the rest. 427 if not convert: 428 # Return to the base directory. 429 chdir(base_dir) 430 431 # Return. 432 return 433 434 print("\n\n\n <<< dvips >>>\n\n\n") 435 system('dvips -R0 -o relax.ps relax.dvi') 436 437 print("\n\n\n <<< ps2pdf >>>\n\n\n") 438 if env['SYSTEM'] == 'Windows': 439 # According to the Ghostscript documentation, "When passing options to ghostcript through a batch 440 # file wrapper such as ps2pdf.bat you need to substitute '#' for '=' as the separator between options 441 # and their arguments." 442 assign = '#' 443 else: 444 assign = '=' 445 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') 446 447 print("\n\n\n <<< Removing the PS file and shifting the PDF down a directory >>>\n\n\n") 448 if access('relax.ps', F_OK): 449 remove('relax.ps') 450 if access('relax.pdf', F_OK): 451 rename('relax.pdf', path.pardir+path.sep+'relax.pdf') 452 453 # Return to the base directory. 454 chdir(base_dir) 455 456 # Final print out. 457 print("\n\n\n")

458 459

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

461 """Builder action for fetching the relax user function docstrings.""" 462 463 # Print out. 464 print('') 465 print("###############################################") 466 print("# Fetching the relax user function docstrings #") 467 print("###############################################\n\n") 468 469 # Import the fetch_docstrings module (needs to be done here so that Sconstruct doesn't need to load the entire program each time). 470 sys.path.append(getcwd()) 471 from docs.latex.fetch_docstrings import Fetch_docstrings 472 473 # Get the docstrings. 474 Fetch_docstrings(env['LATEX_DIR'] + sep + 'docstring.tex') 475 476 # Delete the Fetch_docstrings class. This allows the loaded dll files to be deleted through python on MS Windows. 477 del Fetch_docstrings 478 479 # Final print out. 480 print("\n\n\n")

481 482

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

484 """Builder action for creating the LaTeX relax version file.""" 485 486 # Print out. 487 print('') 488 print("################################################") 489 print("# Creating the LaTeX relax version number file #") 490 print("################################################") 491 492 # Place the program version number into a LaTeX file. 493 file = open(env['LATEX_DIR'] + sep + 'relax_version.tex', 'w') 494 file.write("Version " + version + '\n') 495 file.close() 496 497 # Final print out. 498 print("\n\n\n")

499

Source Code for Module scons.manuals