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

364 365

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

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

400 401

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

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

468 469

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

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

491 492

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

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

514

Source Code for Module scons.manuals