Package scons :: Module manuals
[hide private]
[frames] | no frames]

Source Code for Module 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 printout. 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 # Open the file and read the data. 327 file = open(full_path) 328 lines = file.readlines() 329 file.close() 330 331 # Modify the original file. 332 file = open(full_path, 'w') 333 334 # Loop over the lines. 335 found = False 336 for i in range(len(lines)): 337 # Find the position of </head>. 338 if not found and search('</head>', lines[i]): 339 # Append the head lines. 340 for j in range(len(head_lines)): 341 file.write(head_lines[j]) 342 343 # The found flag. 344 found = True 345 346 # Append the old line. 347 file.write(lines[i]) 348 349 # Close the file. 350 file.close() 351 352 # Final printout. 353 print("\n\n\n")
354 355
356 -def compile_user_manual_html(target, source, env):
357 """Builder action for compiling the user manual (HTML version) from the LaTeX sources.""" 358 359 # Make the PDF manual to generate the aux files. 360 compile_user_manual_pdf(target, source, env, convert=False) 361 362 # Print out. 363 print('') 364 print("############################################") 365 print("# Compiling the user manual (HTML version) #") 366 print("############################################\n\n") 367 368 # Go to the LaTeX directory. 369 base_dir = getcwd() 370 chdir(env['LATEX_DIR']) 371 372 # The target directory. 373 dir = path.pardir + path.sep + "html" 374 375 # Run the latex2html command. 376 cmd = "latex2html -dir %s relax.tex" % (dir) 377 print("Running the command:\n$ %s\n\n\n" % cmd) 378 system(cmd) 379 380 # Create the proper index.html file. 381 cmd = "cp -vp %s%srelax_user_manual.html %s%sindex.html" % (dir, path.sep, dir, path.sep) 382 print("Running the command:\n$ %s\n\n\n" % cmd) 383 system(cmd) 384 385 # Return to the base directory. 386 chdir(base_dir) 387 388 # Final printout. 389 print("\n\n\n")
390 391
392 -def compile_user_manual_pdf(target, source, env, convert=True):
393 """Builder action for compiling the user manual (PDF version) from the LaTeX sources.""" 394 395 # Print out. 396 print('') 397 print("###########################################") 398 print("# Compiling the user manual (PDF version) #") 399 print("###########################################\n\n") 400 401 # Go to the LaTeX directory. 402 base_dir = getcwd() 403 chdir(env['LATEX_DIR']) 404 405 print("\n\n\n <<< LaTeX (first round) >>>\n\n\n") 406 system('latex relax') 407 408 print("\n\n\n <<< Bibtex >>>\n\n\n") 409 system('bibtex relax') 410 411 print("\n\n\n <<< Makeindex >>>\n\n\n") 412 system('makeindex relax') 413 414 print("\n\n\n <<< LaTeX (second round) >>>\n\n\n") 415 system('latex relax') 416 417 print("\n\n\n <<< LaTeX (third round) >>>\n\n\n") 418 system('latex relax') 419 420 print("\n\n\n <<< LaTeX (fourth round) >>>\n\n\n") 421 system('latex relax') 422 423 # Skip the rest. 424 if not convert: 425 # Return to the base directory. 426 chdir(base_dir) 427 428 # Return. 429 return 430 431 print("\n\n\n <<< dvips >>>\n\n\n") 432 system('dvips -R0 -o relax.ps relax.dvi') 433 434 print("\n\n\n <<< ps2pdf >>>\n\n\n") 435 if env['SYSTEM'] == 'Windows': 436 # According to the Ghostscript documentation, "When passing options to ghostcript through a batch 437 # file wrapper such as ps2pdf.bat you need to substitute '#' for '=' as the separator between options 438 # and their arguments." 439 assign = '#' 440 else: 441 assign = '=' 442 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') 443 444 print("\n\n\n <<< Removing the PS file and shifting the PDF down a directory >>>\n\n\n") 445 if access('relax.ps', F_OK): 446 remove('relax.ps') 447 if access('relax.pdf', F_OK): 448 rename('relax.pdf', path.pardir+path.sep+'relax.pdf') 449 450 # Return to the base directory. 451 chdir(base_dir) 452 453 # Final printout. 454 print("\n\n\n")
455 456
457 -def fetch_docstrings(target, source, env):
458 """Builder action for fetching the relax user function docstrings.""" 459 460 # Print out. 461 print('') 462 print("###############################################") 463 print("# Fetching the relax user function docstrings #") 464 print("###############################################\n\n") 465 466 # Import the fetch_docstrings module (needs to be done here so that Sconstruct doesn't need to load the entire program each time). 467 sys.path.append(getcwd()) 468 from docs.latex.fetch_docstrings import Fetch_docstrings 469 470 # Get the docstrings. 471 Fetch_docstrings(env['LATEX_DIR'] + sep + 'docstring.tex') 472 473 # Delete the Fetch_docstrings class. This allows the loaded dll files to be deleted through python on MS Windows. 474 del Fetch_docstrings 475 476 # Final printout. 477 print("\n\n\n")
478 479
480 -def version_file(target, source, env):
481 """Builder action for creating the LaTeX relax version file.""" 482 483 # Print out. 484 print('') 485 print("################################################") 486 print("# Creating the LaTeX relax version number file #") 487 print("################################################") 488 489 # Place the program version number into a LaTeX file. 490 file = open(env['LATEX_DIR'] + sep + 'relax_version.tex', 'w') 491 file.write("Version " + version + '\n') 492 file.close() 493 494 # Final printout. 495 print("\n\n\n")
496