scons.manuals

1 ############################################################################### 2 # # 3 # Copyright (C) 2006-2013 Edward d'Auvergne # 4 # # 5 # This file is part of the program relax (http://www.nmr-relax.com). # 6 # # 7 # This program 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 3 of the License, or # 10 # (at your option) any later version. # 11 # # 12 # This program 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 this program. If not, see <http://www.gnu.org/licenses/>. # 19 # # 20 ############################################################################### 21 22 # Module docstring. 23 """SCons targets for building the relax manuals.""" 24 25 # Python module imports. 26 from glob import glob 27 from os import F_OK, access, chdir, getcwd, listdir, path, remove, rename, sep, system 28 from re import search 29 import sys 30 31 # relax module imports. 32 from status import Status; status = Status() 33 import version 34 35

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

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

85 86

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

88 """Builder action for compiling the API documentation manual (HTML version) using Epydoc.""" 89 90 # Print out. 91 print('') 92 print("#####################################################") 93 print("# Compiling API documentation manual (HTML version) #") 94 print("#####################################################\n\n") 95 96 97 # Set up the Epydoc configuration (adapted from http://epydoc.sourceforge.net/configfile.html). 98 ############################################################################################### 99 100 # exclude 101 # The list of objects to exclude. 102 exclude = [ 103 'devel_scripts', 104 'extern', 105 'graphics', 106 'minfx.scipy_subset', 107 'multi.test_implementation', 108 'multi.test_implementation2', 109 'sample_scripts' 110 ] 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'+sep+'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://www.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="/">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 # Excluded modules. 260 for name in exclude: 261 epydoc_cmd = epydoc_cmd + ' --exclude=' + name 262 263 # All the files of the current directory. 264 blacklist = ['README', 'relax.bat', 'relax_gui_mode.py'] 265 files = listdir(getcwd()) 266 for file in files: 267 # Blacklisted. 268 if file in blacklist: 269 continue 270 271 # The excluded ones. 272 if file in exclude: 273 continue 274 275 # Hidden files and directories. 276 if search('^\.', file): 277 continue 278 279 # Otherwise add it. 280 epydoc_cmd = "%s %s" % (epydoc_cmd, file) 281 282 283 # Execute Epydoc. 284 ################# 285 286 # Print out. 287 print("Running the command:\n$ " + epydoc_cmd + "\n\n\n") 288 289 # System call. 290 system(epydoc_cmd) 291 292 293 294 # Modify the CSS file. 295 ###################### 296 297 # Open the file. 298 css_file = open(target + sep+'epydoc.css', 'a') 299 300 # Header. 301 css_file.write("\n\n\n\n/* Edward */\n\n") 302 303 # Append the new link style to the end. 304 css_file.write("a { text-decoration:none; color:#0017aa; font-weight:normal; }\n") 305 css_file.write("a:hover { color:#316fff; }\n") 306 307 # Close the file. 308 css_file.close() 309 310 311 # Modify all HTML files. 312 ######################## 313 314 # Print out. 315 print("\n\nModifying the <head> tag of all HTML files.\n") 316 317 # The additional head tags. 318 head_lines = [] 319 320 # The Google analytics JS. 321 file = open(status.install_path + sep + 'devel_scripts' + sep + 'google_analytics.js') 322 for line in file.readlines(): 323 head_lines.append(line) 324 file.close() 325 326 # Loop over the files. 327 for file_name in listdir(status.install_path + sep + 'docs' + sep + 'api'): 328 # The full path. 329 full_path = status.install_path + sep + 'docs' + sep + 'api' + sep + file_name 330 331 # Skip all non-html files. 332 if not search('.html$', full_path): 333 continue 334 335 # Open the file and read the data. 336 file = open(full_path) 337 lines = file.readlines() 338 file.close() 339 340 # Modify the original file. 341 file = open(full_path, 'w') 342 343 # Loop over the lines. 344 found = False 345 for i in range(len(lines)): 346 # Find the position of </head>. 347 if not found and search('</head>', lines[i]): 348 # Append the head lines. 349 for j in range(len(head_lines)): 350 file.write(head_lines[j]) 351 352 # The found flag. 353 found = True 354 355 # Append the old line. 356 file.write(lines[i]) 357 358 # Close the file. 359 file.close() 360 361 # Final printout. 362 print("\n\n\n")

363 364

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

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

399 400

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

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

464 465

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

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

487 488

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

490 """Builder action for creating the LaTeX relax version file.""" 491 492 # Print out. 493 print('') 494 print("################################################") 495 print("# Creating the LaTeX relax version number file #") 496 print("################################################") 497 498 # Add the repository revision if not a normal release. 499 text = version.version 500 if text == 'repository checkout': 501 text += ' r' + version.revision() 502 503 # Place the program version number into a LaTeX file. 504 file = open(env['LATEX_DIR'] + sep + 'relax_version.tex', 'w') 505 file.write("Version " + text + '\n') 506 file.close() 507 508 # Final printout. 509 print("\n\n\n")

510

Source Code for Module scons.manuals