scons.manuals

1 ############################################################################### 2 # # 3 # Copyright (C) 2006-2015 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 for file in glob(env['LATEX_DIR'] + 'frame_order' + sep + '*.aux'): 66 files.append(file) 67 68 # Remove the files. 69 for file in files: 70 try: 71 remove(file) 72 except OSError: 73 message = sys.exc_info()[1] 74 75 # The file does not exist. 76 if message.errno == 2: 77 pass 78 79 # All other errors. 80 else: 81 raise 82 else: 83 print("Removing the file " + repr(file) + ".") 84 85 # Final printout. 86 print("\n\n\n")

87 88

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

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

367 368

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

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

403 404

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

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

471 472

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

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

494 495

496 -def replicate_title_check(target, source, env):

497 """Builder action for checking for replicated titles in the LaTeX sources.""" 498 499 # Print out. 500 print('') 501 print("#######################################################") 502 print("# Checking for replicated titles in the LaTeX sources #") 503 print("#######################################################\n\n") 504 505 # Import the find_replicate_titles module (needs to be done here so that Sconstruct doesn't need to load the entire program each time). 506 sys.path.append(getcwd()) 507 from docs.latex.find_replicate_titles import Replicated_titles 508 509 # Find the replicates. 510 replicates = Replicated_titles() 511 if replicates.find(): 512 print("\n\nFatal error: Replicated titles found.") 513 print("\n\n\n") 514 sys.exit(1) 515 516 # Delete the Replicate_titles class. This allows the loaded dll files to be deleted through python on MS Windows. 517 del replicates 518 del Replicated_titles 519 520 # Final printout. 521 print("No replicated titles found.") 522 print("\n\n\n")

523 524

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

526 """Builder action for creating the LaTeX relax version file.""" 527 528 # Print out. 529 print('') 530 print("################################################") 531 print("# Creating the LaTeX relax version number file #") 532 print("################################################") 533 534 # Add the repository revision if not a normal release. 535 text = version.version 536 if text == 'repository checkout': 537 text += ' r%s' % version.repo_revision 538 539 # Place the program version number into a LaTeX file. 540 file = open(env['LATEX_DIR'] + sep + 'relax_version.tex', 'w') 541 file.write("Version " + text + '\n') 542 file.close() 543 544 # Final printout. 545 print("\n\n\n")

546

Source Code for Module scons.manuals