Author: bugman
Date: Thu Oct 12 08:33:45 2006
New Revision: 2626
URL: http://svn.gna.org/viewcvs/relax?rev=2626&view=rev
Log:
Added the API documentation creation (using Epydoc) to the Scons scripts.
The Scons target to create the HTML API documentation is called
'api_manual_html'. The
documentation can be created by typing:
$ scons api_manual_html
The function 'compile_api_manual_html()' was added to the 'scons/manuals.py'
file. This function
runs the 'epydoc' command. All the Epydoc options are specified in that
function.
Modified:
1.2/scons/manuals.py
1.2/sconstruct
Modified: 1.2/scons/manuals.py
URL:
http://svn.gna.org/viewcvs/relax/1.2/scons/manuals.py?rev=2626&r1=2625&r2=2626&view=diff
==============================================================================
--- 1.2/scons/manuals.py (original)
+++ 1.2/scons/manuals.py Thu Oct 12 08:33:45 2006
@@ -81,6 +81,199 @@
print "\n\n\n"
+def compile_api_manual_html(target, source, env):
+ """Builder action for compiling the API documentation manual (HTML
version) using Epydoc."""
+
+ # Print out.
+ print
+ print "#####################################################"
+ print "# Compiling API documentation manual (HTML version) #"
+ print "#####################################################\n\n"
+
+
+ # Set up the Epydoc configuration (adapted from
http://epydoc.sourceforge.net/configfile.html).
+
###############################################################################################
+
+ # modules
+ # The list of objects to document.
+ modules = ['relax',
+ '*.py',
+ 'docs/*.py',
+ 'docs/latex/*.py',
+ 'dx/*.py',
+ 'generic_fns/*.py',
+ 'maths_fns/*.py',
+ 'prompt/*.py',
+ 'specific_fns/*.py',
+ 'test_suite/*.py',
+ 'sconstruct',
+ 'scons/*.py']
+
+ # output
+ # The type of output that should be generated. Should be one
+ # of: html, text, latex, dvi, ps, pdf.
+ output = 'html'
+
+ # target
+ # The path to the output directory. May be relative or absolute.
+ target = 'docs/api'
+
+ # docformat
+ # The default markup language for docstrings, for modules that do
+ # not define __docformat__.
+ docformat = 'epytext'
+
+ # css
+ # The CSS stylesheet for HTML output. Can be the name of a builtin
+ # stylesheet, or the name of a file.
+ css = 'white'
+
+ # name
+ # The documented project's name.
+ name = 'relax'
+
+ # url
+ # The documented project's URL.
+ url = 'http://nmr-relax.com'
+
+ # link
+ # HTML code for the project link in the navigation bar. If left
+ # unspecified, the project link will be generated based on the
+ # project's name and URL.
+ #link = '<a href="http://nmr-relax.com";>relax</a>'
+
+ # top
+ # The "top" page for the documentation. Can be a URL, the name
+ # of a module or class, or one of the special names "trees.html",
+ # "indices.html", or "help.html"
+ # top = 'os.path'
+
+ # help
+ # An alternative help file. The named file should contain the
+ # body of an HTML file; navigation bars will be added to it.
+ # help = 'my_helpfile.html'
+
+ # frames
+ # Whether or not to include a frames-based table of contents.
+ frames = 1
+
+ # private
+ # Whether or not to inclue private variables. (Even if included,
+ # private variables will be hidden by default.)
+ private = 1
+
+ # imports
+ # Whether or not to list each module's imports.
+ imports = 1
+
+ # verbosity
+ # An integer indicating how verbose epydoc should be. The default
+ # value is 0; negative values will supress warnings and errors;
+ # positive values will give more verbose output.
+ verbosity = 1
+
+ # parse
+ # Whether or not parsing should be used to examine objects.
+ parse = 1
+
+ # introspect
+ # Whether or not introspection should be used to examine objects.
+ introspect = 1
+
+ # graph
+ # The list of graph types that should be automatically included
+ # in the output. Graphs are generated using the Graphviz "dot"
+ # executable. Graph types include: "classtree", "callgraph",
+ # "umlclass". Use "all" to include all graph types
+ graph = 'all'
+
+ # dotpath
+ # The path to the Graphviz "dot" executable, used to generate
+ # graphs.
+ #dotpath = '/usr/local/bin/dot'
+
+ # sourcecode
+ # Whether or not to include syntax highlighted source code in
+ # the output (HTML only).
+ sourcecode = 1
+
+ # pstat
+ # The name of one or more pstat files (generated by the profile
+ # or hotshot module). These are used to generate call graphs.
+ #pstat = 'profile.out'
+
+ # separate-classes
+ # Whether each class should be listed in its own section when
+ # generating LaTeX or PDF output.
+ #separate-classes = 0
+
+
+
+ # Construct the command line string.
+ ####################################
+
+ # Program name, output, target, docformat, css, name, and url.
+ epydoc_cmd = 'epydoc' + ' --' + output + ' -o ' + target + ' --docformat
' + docformat + ' --css ' + css + ' --name ' + name + ' --url ' + url
+
+ # Frames.
+ if frames:
+ epydoc_cmd = epydoc_cmd + ' --show-frames'
+ else:
+ epydoc_cmd = epydoc_cmd + ' --no-frames'
+
+ # Private variables.
+ if private:
+ epydoc_cmd = epydoc_cmd + ' --show-private'
+ else:
+ epydoc_cmd = epydoc_cmd + ' --no-private'
+
+ # Module imports.
+ if imports:
+ epydoc_cmd = epydoc_cmd + ' --show-imports'
+ else:
+ epydoc_cmd = epydoc_cmd + ' --no-imports'
+
+ # Verbosity.
+ if verbosity > 0:
+ for i in range(verbosity):
+ epydoc_cmd = epydoc_cmd + ' -v'
+ elif verbosity < 0:
+ for i in range(-verbosity):
+ epydoc_cmd = epydoc_cmd + ' -q'
+
+ # Parsing and introspection.
+ if parse and not introspect:
+ epydoc_cmd = epydoc_cmd + ' --parse-only'
+ elif not parse and introspect:
+ epydoc_cmd = epydoc_cmd + ' --introspect-only'
+
+ # Graph.
+ epydoc_cmd = epydoc_cmd + ' --graph ' + graph
+
+ # Sourcecode.
+ if sourcecode:
+ epydoc_cmd = epydoc_cmd + ' --show-sourcecode'
+ else:
+ epydoc_cmd = epydoc_cmd + ' --no-sourcecode'
+
+ # Modules.
+ for module in modules:
+ epydoc_cmd = epydoc_cmd + ' ' + module
+
+
+ # Execute Epydoc.
+ #################
+
+ # Print out.
+ print "Running the command:\n$ " + epydoc_cmd + "\n\n\n"
+
+ # System call.
+ system(epydoc_cmd)
+
+ # Final print out.
+ print "\n\n\n"
+
+
def compile_user_manual_html(target, source, env):
"""Builder action for compiling the HTML version of the user manual from
the LaTeX sources."""
Modified: 1.2/sconstruct
URL:
http://svn.gna.org/viewcvs/relax/1.2/sconstruct?rev=2626&r1=2625&r2=2626&view=diff
==============================================================================
--- 1.2/sconstruct (original)
+++ 1.2/sconstruct Thu Oct 12 08:33:45 2006
@@ -42,7 +42,7 @@
# relax and Scons modules.
-from scons.manuals import clean_manual_files, compile_user_manual_html,
compile_user_manual_pdf, fetch_docstrings, version_file
+from scons.manuals import clean_manual_files, compile_api_manual_html,
compile_user_manual_html, compile_user_manual_pdf, fetch_docstrings,
version_file
from version import version
@@ -204,6 +204,11 @@
manual_env.Depends('user_manual_html_nofetch', 'manual_version_file')
manual_env.Depends('user_manual_html_nofetch',
'compile_user_manual_html')
+ # Target for creating the HTML version of the API documentation
manual.
+ manual_env.Manual(target='api_manual_html', source=None)
+ manual_env.Depends('api_manual_html', 'manual_clean')
+ manual_env.Depends('api_manual_html', 'compile_api_manual_html')
+
# Target for creating relax version number LaTeX file.
manual_env.Append(BUILDERS={'Version' :
Builder(action=version_file)})
@@ -220,6 +225,10 @@
# Target for compiling the HTML version of the user manual from the
LaTeX sources.
manual_env.Append(BUILDERS={'CompileUserManualHTML' :
Builder(action=compile_user_manual_html)})
manual_env.CompileUserManualHTML(target='compile_user_manual_html',
source=None)
+
+ # Target for compiling the HTML version of the API documentation
manual using Epydoc.
+ manual_env.Append(BUILDERS={'CompileAPIManualHTML' :
Builder(action=compile_api_manual_html)})
+ manual_env.CompileAPIManualHTML(target='compile_api_manual_html',
source=None)
# Clean target.
manual_env.Append(BUILDERS={'Clean' :
Builder(action=clean_manual_files)})
r2626 - in /1.2: scons/manuals.py sconstruct