scons.manuals

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

365 366

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

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

401 402

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

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

469 470

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

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

492 493

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

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

515

Source Code for Module scons.manuals