"scons doc" still tries to build all of the swig things (and doesn't actually build the documentation), despite being the obvious thing for a user to try if they want to build documentation. While the examples happen to be in the doc hierarchy, running them is part of test, and so they shouldn't be run when the user wants to build docs.

Also, the docs generated from doxygen should be in doc/html since they are the IMP html documentation and the fact that they are generated using doxygen is an implementation detail.

On Jan 11, 2009, at 3:36 PM, Notification of IMP commits wrote:

> Author: ben@SALILAB.ORG > Date: 2009-01-11 15:36:27 -0800 (Sun, 11 Jan 2009) > New Revision: 1155 > > Added: > trunk/doc/doxygen/ > trunk/doc/doxygen/footer.html > trunk/doc/doxygen/header.html > trunk/doc/doxygen/layout.xml > trunk/kernel/doc/api.dox > trunk/kernel/doc/conventions.dox > trunk/kernel/doc/decorators.dox > trunk/kernel/doc/deprecation.dox > trunk/kernel/doc/developer_guide.dox > trunk/kernel/doc/developers.dox > trunk/kernel/doc/introduction.dox.in > trunk/kernel/doc/main.dox > trunk/kernel/doc/makemodule.dox > trunk/tools/colorize_python.py > trunk/tools/generate_doxygen.py > trunk/tools/make_examples.py > Removed: > trunk/doc/html/ > trunk/doc/internal/ > trunk/doc/manual.xml > trunk/doc/usage.xml > trunk/kernel/doc/bin/ > trunk/kernel/doc/doxygen/ > trunk/kernel/doc/inputs/ > trunk/patches/remove_docbook.patch > trunk/patches/remove_docbook.readme > Modified: > trunk/doc/SConscript > trunk/doc/doxygen/SConscript > trunk/doc/doxygen/doxygen.conf.in > trunk/kernel/SConscript > trunk/kernel/doc/ > trunk/kernel/doc/SConscript > trunk/tools/__init__.py > Log: > Remove the old DocBook documentation (should be covered by the > doxygen docs > and the wiki now). Incorporate Daniel's changes to the doxygen docs, > auto-generating any necessary files during the build process. > > > Modified: trunk/doc/SConscript > =================================================================== > --- trunk/doc/SConscript 2009-01-11 23:33:46 UTC (rev 1154) > +++ trunk/doc/SConscript 2009-01-11 23:36:27 UTC (rev 1155) > @@ -1,3 +1,2 @@ > -SConscript('html/SConscript') > -SConscript('internal/SConscript') > +SConscript('doxygen/SConscript') > SConscript('examples/SConscript') > > > Property changes on: trunk/doc/doxygen > ___________________________________________________________________ > Added: svn:ignore > + .examples > doxygen.conf > html > > Added: svn:mergeinfo > + > > Modified: trunk/doc/doxygen/SConscript > =================================================================== > --- trunk/doc/internal/SConscript 2009-01-09 16:03:46 UTC (rev 1147) > +++ trunk/doc/doxygen/SConscript 2009-01-11 23:36:27 UTC (rev 1155) > @@ -3,8 +3,6 @@ > import os.path > > dox = env.Doxygen("html/index.html", "doxygen.conf") > -# Force the population of the build/include/ directory with > generated headers > -env.Depends(dox, '#/build/include') > > docdir = os.path.join(env['docdir'], 'doxygen') > > @@ -24,10 +22,13 @@ > # Expand out ALL_MODULES to a list of all modules, one > per line > for mod in env['IMP_MODULES_ALL']: > outfile.write(line.replace('@ALL_MODULES@', mod)) > - else: > + elif not line.startswith('#'): > outfile.write(line) > infile.close() > outfile.close() > > env.Append(BUILDERS = {'GenerateDoxygen': > Builder(action=generate_doxygen)}) > env.GenerateDoxygen("doxygen.conf", "doxygen.conf.in") > + > +examples = env.MakeExamples(".examples/examples.dox", None) > +env.AlwaysBuild(examples) > > Modified: trunk/doc/doxygen/doxygen.conf.in > =================================================================== > --- trunk/doc/internal/doxygen.conf.in 2009-01-09 16:03:46 UTC (rev > 1147) > +++ trunk/doc/doxygen/doxygen.conf.in 2009-01-11 23:36:27 UTC (rev > 1155) > @@ -180,7 +180,13 @@ > # You can put \n's in the value part of an alias to insert newlines. > > ALIASES = "command{1}=\code \1 \endcode" \ > - "imp=\p IMP" > + "salilab{2}=<a href="https://salilab.org/ > \1"><b>\2</b></a>" \ > + "external{2}=<a href="https://%5C1%5C%22%3E<b>\2</ > b></a>" \ > + "imp=\p IMP" \ > + "wiki{2}=<a href="https://salilab.org/imp/wiki/ > \1/"><b>\2</b></a>" \ > + "string{1}=<tt>\1</tt>" \ > + "impdev=<a href="https://salilab.org/mailman/listinfo/imp-dev > "><b>imp-dev</b></a>" \ > + "impcommit=<a href="https://salilab.org/mailman/listinfo/imp-commit > "><b>imp-commit</b></a>" > > # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists > of C > # sources only. Doxygen will then generate output that is more > tailored for C. > @@ -491,7 +497,7 @@ > # file name after the option, if omitted DoxygenLayout.xml will be > used as the name > # of the layout file. > > -LAYOUT_FILE = > +LAYOUT_FILE = layout.xml > > #--------------------------------------------------------------------------- > # configuration options related to warning and progress messages > @@ -555,7 +561,8 @@ > > INPUT = ../../build/include \ > ../../modules/@ALL_MODULES@/doc \ > - ../../kernel/doc > + ../../kernel/doc \ > + . > > > # This tag can be used to specify the character encoding of the > source files > @@ -630,7 +637,8 @@ > # and *.h) to filter out the source-files in the directories. If left > # blank all files are included. > > -EXAMPLE_PATTERNS = *.py > +EXAMPLE_PATTERNS = *.py \ > + *.cpp > > # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories > will be > # searched for input files to be used with the \include or > \dontinclude > @@ -773,13 +781,13 @@ > # each generated HTML page. If it is left blank doxygen will > generate a > # standard header. > > -HTML_HEADER = ../../kernel/doc/header.html > +HTML_HEADER = header.html > > # The HTML_FOOTER tag can be used to specify a personal HTML footer > for > # each generated HTML page. If it is left blank doxygen will > generate a > # standard footer. > > -HTML_FOOTER = ../../kernel/doc/footer.html > +HTML_FOOTER = footer.html > > # The HTML_STYLESHEET tag can be used to specify a user-defined > cascading > # style sheet that is used by each HTML page. It can be used to > > Copied: trunk/doc/doxygen/footer.html (from rev 1147, trunk/kernel/ > doc/doxygen/footer.html) > =================================================================== > --- trunk/doc/doxygen/footer.html (rev 0) > +++ trunk/doc/doxygen/footer.html 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,4 @@ > +<hr size="1"><address style="text-align: right;"><small> > +Generated on $datetime for $projectname by&nbsp;<a href="http://www.doxygen.org/index.html > ">doxygen</a> $doxygenversion</small></address> > +</body> > +</html> > > Copied: trunk/doc/doxygen/header.html (from rev 1147, trunk/kernel/ > doc/doxygen/header.html) > =================================================================== > --- trunk/doc/doxygen/header.html (rev 0) > +++ trunk/doc/doxygen/header.html 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,6 @@ > +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> > +<html><head><meta http-equiv="Content-Type" content="text/ > html;charset=UTF-8"> > +<title>$title</title> > +<link href="doxygen.css" rel="stylesheet" type="text/css"> > +<link href="tabs.css" rel="stylesheet" type="text/css"> > +</head><body> > > Copied: trunk/doc/doxygen/layout.xml (from rev 1147, trunk/kernel/ > doc/doxygen/layout.xml) > =================================================================== > --- trunk/doc/doxygen/layout.xml (rev 0) > +++ trunk/doc/doxygen/layout.xml 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,182 @@ > +<doxygenlayout version="1.0"> > + <!-- Navigation index tabs for HTML output --> > + <navindex> > + <tab type="mainpage" visible="yes" title=""/> > + <tab type="pages" visible="yes" title=""/> > + <tab type="modules" visible="no" title=""/> > + <tab type="namespaces" visible="yes" title=""> > + <tab type="namespaces" visible="yes" title=""/> > + <tab type="namespacemembers" visible="yes" title=""/> > + </tab> > + <tab type="hierarchy" visible="yes" title=""/> > + <tab type="classindex" visible="yes" title=""/> > + <tab type="classes" visible="no" title=""> > + <tab type="classes" visible="no" title=""/> > + <tab type="classmembers" visible="no" title=""/> > + </tab> > + <tab type="files" visible="no" title=""> > + <tab type="files" visible="no" title=""/> > + <tab type="globals" visible="no" title=""/> > + </tab> > + <tab type="dirs" visible="no" title=""/> > + <tab type="examples" visible="yes" title=""/> > + </navindex> > + > + <!-- Layout definition for a class page --> > + <class> > + <briefdescription visible="yes"/> > + <includes visible="$SHOW_INCLUDE_FILES"/> > + <inheritancegraph visible="$CLASS_GRAPH"/> > + <collaborationgraph visible="$COLLABORATION_GRAPH"/> > + <allmemberslink visible="yes"/> > + <memberdecl> > + <membergroups visible="yes"/> > + <nestedclasses visible="yes" title=""/> > + <publictypes title=""/> > + <publicslots title=""/> > + <signals title=""/> > + <publicmethods title=""/> > + <publicstaticmethods title=""/> > + <publicattributes title=""/> > + <publicstaticattributes title=""/> > + <protectedtypes title=""/> > + <protectedslots title=""/> > + <protectedmethods title=""/> > + <protectedstaticmethods title=""/> > + <protectedattributes title=""/> > + <protectedstaticattributes title=""/> > + <packagetypes title=""/> > + <packagemethods title=""/> > + <packagestaticmethods title=""/> > + <packageattributes title=""/> > + <packagestaticattributes title=""/> > + <properties title=""/> > + <events title=""/> > + <privatetypes title=""/> > + <privateslots title=""/> > + <privatemethods title=""/> > + <privatestaticmethods title=""/> > + <privateattributes title=""/> > + <privatestaticattributes title=""/> > + <friends title=""/> > + <related title="" subtitle=""/> > + </memberdecl> > + <detaileddescription title=""/> > + <memberdef> > + <typedefs title=""/> > + <enums title=""/> > + <constructors title=""/> > + <functions title=""/> > + <related title=""/> > + <variables title=""/> > + <properties title=""/> > + <events title=""/> > + </memberdef> > + <usedfiles visible="$SHOW_USED_FILES"/> > + <authorsection visible="yes"/> > + </class> > + > + <!-- Layout definition for a namespace page --> > + <namespace> > + <briefdescription visible="yes"/> > + <memberdecl> > + <nestednamespaces visible="yes" title=""/> > + <classes visible="yes" title=""/> > + <membergroups visible="yes"/> > + <typedefs title=""/> > + <enums title=""/> > + <functions title=""/> > + <variables title=""/> > + </memberdecl> > + <detaileddescription title=""/> > + <memberdef> > + <typedefs title=""/> > + <enums title=""/> > + <functions title=""/> > + <variables title=""/> > + </memberdef> > + <authorsection visible="yes"/> > + </namespace> > + > + <!-- Layout definition for a file page --> > + <file> > + <briefdescription visible="yes"/> > + <includes visible="$SHOW_INCLUDE_FILES"/> > + <includegraph visible="$INCLUDE_GRAPH"/> > + <includedbygraph visible="$INCLUDED_BY_GRAPH"/> > + <sourcelink visible="yes"/> > + <memberdecl> > + <classes visible="yes" title=""/> > + <namespaces visible="yes" title=""/> > + <defines title=""/> > + <typedefs title=""/> > + <enums title=""/> > + <functions title=""/> > + <variables title=""/> > + </memberdecl> > + <detaileddescription title=""/> > + <memberdef> > + <defines title=""/> > + <typedefs title=""/> > + <enums title=""/> > + <functions title=""/> > + <variables title=""/> > + </memberdef> > + <authorsection/> > + </file> > + > + <!-- Layout definition for a group page --> > + <group> > + <briefdescription visible="yes"/> > + <groupgraph visible="$GROUP_GRAPHS"/> > + <memberdecl> > + <classes visible="yes" title=""/> > + <namespaces visible="yes" title=""/> > + <dirs visible="yes" title=""/> > + <nestedgroups visible="yes" title=""/> > + <files visible="yes" title=""/> > + <defines title=""/> > + <typedefs title=""/> > + <enums title=""/> > + <enumvalues title=""/> > + <functions title=""/> > + <variables title=""/> > + <signals title=""/> > + <publicslots title=""/> > + <protectedslots title=""/> > + <privateslots title=""/> > + <events title=""/> > + <properties title=""/> > + <friends title=""/> > + </memberdecl> > + <detaileddescription title=""/> > + <memberdef> > + <pagedocs/> > + <defines title=""/> > + <typedefs title=""/> > + <enums title=""/> > + <enumvalues title=""/> > + <functions title=""/> > + <variables title=""/> > + <signals title=""/> > + <publicslots title=""/> > + <protectedslots title=""/> > + <privateslots title=""/> > + <events title=""/> > + <properties title=""/> > + <friends title=""/> > + </memberdef> > + <authorsection visible="yes"/> > + </group> > + > + <!-- Layout definition for a directory page --> > + <directory> > + <briefdescription visible="yes"/> > + <directorygraph visible="yes"/> > + <memberdecl> > + <dirs visible="yes"/> > + <files visible="yes"/> > + </memberdecl> > + <detaileddescription title=""/> > + </directory> > +</doxygenlayout> > > > Property changes on: trunk/doc/doxygen/layout.xml > ___________________________________________________________________ > Added: svn:mergeinfo > + > > Modified: trunk/kernel/SConscript > =================================================================== > --- trunk/kernel/SConscript 2009-01-11 23:33:46 UTC (rev 1154) > +++ trunk/kernel/SConscript 2009-01-11 23:36:27 UTC (rev 1155) > @@ -2,6 +2,7 @@ > > # Subdirectories: > src = SConscript('src/SConscript') > +SConscript('doc/SConscript') > SConscript('include/SConscript') > pyext = SConscript('pyext/SConscript') > test = SConscript('test/SConscript') > > > Property changes on: trunk/kernel/doc > ___________________________________________________________________ > Added: svn:ignore > + .generated > > > Modified: trunk/kernel/doc/SConscript > =================================================================== > --- trunk/kernel/doc/SConscript 2009-01-11 23:33:46 UTC (rev 1154) > +++ trunk/kernel/doc/SConscript 2009-01-11 23:36:27 UTC (rev 1155) > @@ -1,37 +1,4 @@ > Import('env') > > -import os.path > - > -dox = env.Doxygen("#/doc/html/index.html", "doxygen/doxygen.conf") > -# Force the population of the build/include/ directory with > generated headers > -env.Depends(dox, ['#/build/include', 'doxygen/layout.xml']) > - > -docdir = os.path.join(env['docdir'], 'doxygen') > - > -# Install all files from 'dox' directory into the 'docdir' > directory (cannot > -# use env.InstallAs() right now, due to scons bug #1751) > -env.Command(Dir(env.subst(docdir)), dox, > - "install -d $TARGET && install ${SOURCE.dir}/* $TARGET") > - > -# Generate doxygen.conf from doxygen.conf.in > -def generate_doxygen(target, source, env): > - infile = file(source[0].path, 'r') > - outfile = file(target[0].path, 'w') > - print >> outfile, "# Auto-generated by SConscript; do NOT edit > directly!" > - print >> outfile, "# Edit %s instead\n" % source[0].path > - for line in infile: > - if '@ALL_MODULES@' in line: > - # Expand out ALL_MODULES to a list of all modules, one > per line > - for mod in env['IMP_MODULES_ALL']: > - outfile.write(line.replace('@ALL_MODULES@', mod)) > - elif not line.startswith("#") and not line =="\n": > - outfile.write(line) > - infile.close() > - outfile.close() > - env.Execute("./kernel/doc/bin/make-examples") > - > -env.Append(BUILDERS = {'GenerateDoxygen': > Builder(action=generate_doxygen)}) > -gd=env.GenerateDoxygen("doxygen/doxygen.conf", "doxygen/ > doxygen.conf.in") > -env.Depends(gd, Glob("inputs/*.in")) > - > -Return('dox') > +for f in Glob("*.dox.in"): > + env.GenerateDoxFromIn(f) > > Copied: trunk/kernel/doc/api.dox (from rev 1147, trunk/kernel/doc/ > inputs/api.dox.in) > =================================================================== > --- trunk/kernel/doc/api.dox (rev 0) > +++ trunk/kernel/doc/api.dox 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,41 @@ > +/** > + \page api API Documentation > + > + \section intro Introduction > + > + This is the API reference for \imp, an Integrative Modeling > Platform. > + If you are new to \imp, you should familiarize yourself with > the following > + pages first: > + - \ref decorators "Using Decorators" > + - \ref log "Logging Support" > + - \ref assert "Error Reporting Facilities" > + - \ref deprecation "Deprecated Functionality" > + > + Then look through the examples which can be found at: > + - \ref Examples "Examples" > + > + There are a variety of useful base classes which are used to > provide > + most functionality. They are: > + - IMP::Model > + - IMP::Particle > + - IMP::Restraint > + - IMP::ScoreState > + - IMP::Optimizer > + - IMP::core::SingletonContainer, IMP::core::PairContainer > + - IMP::SingletonScore, IMP::PairScore, IMP::TripletScore > + - IMP::core::SingletonModifier, IMP::core::PairModifier, > IMP::core::TripletModifier > + > + There are a few blocks of functionality that cut across > modules. They are > + - \ref hierarchy "Code to create and manipulate hierarchies" > + - \ref bond "Code to create and manipulate bonds" > + > + When programming with \imp, one of the more useful pages is the > + <a href="hierarchy.html"><b>class hierarchy</b></a> as well as > the module main > + pages: > + - IMP > + - IMP::core > + - IMP::misc > + - IMP::em > + - IMP::domino > + - IMP::saxs > +*/ > \ No newline at end of file > > Copied: trunk/kernel/doc/conventions.dox (from rev 1147, trunk/ > kernel/doc/inputs/conventions.dox.in) > =================================================================== > --- trunk/kernel/doc/conventions.dox (rev 0) > +++ trunk/kernel/doc/conventions.dox 2009-01-11 23:36:27 UTC (rev > 1155) > @@ -0,0 +1,154 @@ > +/** > + \page coding_conventions IMP coding conventions > + > + To ensure code consistency and readability, certain conventions > should be > + adhered to when writing code for \imp. Some of these > conventions are > + automatically checked for by source control before allowing a > new commit, and > + can also be checked yourself in new code by running > + \command{scons standards} > + > + \section indent Indentation > + > + All C++ headers and code should > + be indented in 'Linux' style, with 2-space indents. Do not use > + tabs. This is roughly the output of Artistic Style run like > + \command{astyle --convert-tabs --style=linux --indent=spaces=2 > --unpad=paren --pad=oper} > + Split lines if necessary to ensure that > + no line is longer than 80 characters. > + > + All Python code should conform to the > + \external{www.python.org/dev/peps/pep-0008/, Python style guide}. > + In essence this > + translates to 4-space indents, no tabs, and similar class, method > + and variable naming to the C++ code. You can ensure that your > + Python code is correctly indented by using the > + \command{tools/reindent.py} script, available as part of the \imp > + distribution. > + > + > + \section docs Documentation > + > + Format to allow Doxygen automated documentation creation. If > + possible, and appropriate, specify both a 'brief' description and > + a more detailed one (in which parameters, return values, and > + exceptions are documented). Use \c //! for the one-line brief > + description and \c /** ... * / for the multi-line detailed > + description (put the closing * / on a new line, so that these > + comments are always multi-line (Doxygen will not accept both a > + 'brief' comment and a one-line detailed comment). All header and > + source files should have a starting comment header, using the > + \b \file command to document the purpose of the file. > + > + For example: > + \verbatim > + //! Calculates the square root. > + /** \param[in] the_value Calculate the square root of this value. > + \exception ValueException if value is out of range > (negative). > + \return the square root of the given value. > + */ > + \endverbatim > + > + Python code should provide python doc strings. > + > + > + \section names Names > + - Class names should be in \c CamelCase > + - method names and variables should be \c > separated_by_underscores > + - member variables should \c end_in_an_underscore_ > + - member methods that get a value should begin with \c set_ > + - member methods which return a value should begin with \c get_ > + - all preprocessor symbols (things created by #define) must > begin with \c IMP_ > + > + Do not use abbreviations in names. > + > + \b Rational: This makes it easier to tell between class names and > + function names where this is ambiguous (particularly an issue > with > + the Python interface). The Python guys also mandate CamelCase for > + their class names, so this avoids any need to rename classes > + between C++ and Python to ensure clean Python code. Good naming > is > + especially important with preprocessor symbols since these have > + file scope and so can change the meaning of other people's code. > + > + \section errors Errors > + Classes and methods should use IMP exceptions to report errors. > See > + IMP::Exception for a list of existing exceptions. See \ref > assert for > + a list of functions to aid in error reporting and detection. > + \note Do not use exception specifications. Instead document the > + exceptions in Doxygen using the \c \exception command. > + > + > + \section coding Good Coding Practices > + > + - Restraints and ScoreStates should generally use a > + SingletonContainer (or other type of Container) to store the > set of > + Particles that they act on. > + > + - Never use \c using \c namespace outside of a function, instead > + explicitly provide the namespace. > + > + - Use the provided \c IMPMODULE_BEGIN_NAMESPACE, > + \c IMPMODULE_END_NAMESPACE, \c IMPMODULE_BEGIN_INTERNAL_NAMESPACE > + and \c IMPMODULE_END_INTERNAL_NAMESPACE macros to put declarations > + in a namespace appropriate for module \c MODULE. > + > + - Never use the preprocessor to define constants. Use \c const > + variables instead. Proprocessor symbols don't have scope or > type > + and so can have unexpected effects. > + > + - Pass objects which inherit from IMP::Object or > + IMP::RefCountedObject by pointer. Store pointers to such > objects > + using an IMP::Pointer to properly manage reference counting and > + pointer initialization. > + > + - Pass other objects by value or by \c const & (if the object is > + large) and store copies of them. > + > + - Never expose member variables in an object which has methods. > + > + - Try to limit methods to having at most one argument of a given > + type. Otherwise it is easy to mix up the order of arguments > and > + the compiler will not catch it for you. Int and Float count as > + equivalent types for this rule since the compiler will > invisible > + convert an Int into a Float. > + > + - Do not copy and paste large blocks of code to create new > + functionality. Figure out a way to reuse the existing code by > + pulling it into a function and adding extra parameters. When > you > + find bugs, you won't remember to fix them in all the copies of > + the code. > + > + - Clearly mark any file that is created by a script so that other > + people know to edit the original file. > + > + - Always return a \c const value or \c const ref if you are not > + providing write access. Returning a \c const copy means the > compiler > + which create an error if the caller tries to modify the > return value > + without creating a copy of the return value. > + > + - Include files from the local module first, then files from > the other \imp > + modules and kernel and finally outside includes. This makes any > dependencies > + in your code obvious, and by including standard headers \e > after IMP headers, > + any missing includes in the headers themselves show up early > (rather than > + being masked by other headers you include). > + \code > + #include <IMP/mymodule/mymodule_exports.h> > + #include <IMP/mymodlule/MyRestraint.h> > + #include <IMP/Restraint.h> > + #include <vector> > + \endcode > + > + - All classes should have a \c show method which takes an > optional > + \c std::ostream and prints information about the object. In > addition they > + should have \c operator<< defined. This can be easily done > using the > + IMP_OUTPUT_OPERATOR macro. > + > + - Use Int, Float, String rather than \c int, \c float, and \c > std::string. > + > + - Do not use nested classes in the API as SWIG can't wrap them > properly. > + > + - All access to particles should be through decorators. Use the > provided > + macros to help making the decorator. > + > + - Delay initialization of keys until they are actually needed > (since all initialized > + keys take up memory within each particle, more or less). > +*/ > > Copied: trunk/kernel/doc/decorators.dox (from rev 1147, trunk/kernel/ > doc/inputs/decorators.dox.in) > =================================================================== > --- trunk/kernel/doc/decorators.dox (rev 0) > +++ trunk/kernel/doc/decorators.dox 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,47 @@ > +/** \page decorators Decorators > +Decorators wrap particles in order to provide a higher level > interface to > +manipulate the attributes of the particle. They can be used to > +- maintain invariants: e.g. each of the particles have all of x,y,z > coordinates > +- add functionality: e.g. you can get the coordinates as an > IMP::Vector3D > +- provide uniform names for attributes: so you don't use "x" some > places > +and "X" other places > +- cache keys since those can be expensive to create > + > +\note In general, you should not access particle attributes except > +through decorators > + > +To see a list of all available decorators, look at the > IMP::DecoratorBase > +page. > + > + > +The general usage of the decorators is quite simple > +- Create a decorator around a particle which does not have the needed > +attributes. This adds the attributes. > +\verbatim > +d= IMP.core.MyDecorator.create(p) > +\endverbatim > +- Cast a particle which has the required attributes to a decorator, > +checking that it has the attributes > +\verbatim > +d= IMP.core.MyDecorator.cast(p) > +\endverbatim > +- Wrap a particle which is known to have the required attributes in a > +decorator. No checks are necessarily made > +\verbatim > +d= IMP.core.MyDecorator(p) > +\endverbatim > +- Access and manipulate attributes or groups of attributes through > +methods like > +\verbatim > +x=d.get_foo() > +d.set_foo(1.0) > +\endverbatim > +- When needed, access the keys used by the decorator through > methods like > +\verbatim > +d.get_foo_key() > +\endverbatim > + > +See the \ref decorator example for how to implement a simple > +decorator. > + */ > + > > Copied: trunk/kernel/doc/deprecation.dox (from rev 1147, trunk/ > kernel/doc/inputs/deprecation.dox.in) > =================================================================== > --- trunk/kernel/doc/deprecation.dox (rev 0) > +++ trunk/kernel/doc/deprecation.dox 2009-01-11 23:36:27 UTC (rev > 1155) > @@ -0,0 +1,16 @@ > +/** > + \page deprecation Deprecated Functionality > + > + From time to time, \imp is updated in ways that break backward > compatibility. > + In certain cases we will leave the old functionality in so as not > to break > + existing code which uses \imp. Such code is said to be > "deprecated". > + > + Deprecated classes are marked in a variety of ways: > + - They are listed in the "Deprecated List" in the "Related Pages" > tab. > + - They are noted as deprecated in their documentation. > + - They print an warning when an instance is constructed or the > function > + is called. > + > + The warnings can be turned off using the > IMP::core::set_print_deprecation_messages > + function. > +*/ > \ No newline at end of file > > Copied: trunk/kernel/doc/developer_guide.dox (from rev 1147, trunk/ > kernel/doc/inputs/developer_guide.dox.in) > =================================================================== > --- trunk/kernel/doc/developer_guide.dox > (rev 0) > +++ trunk/kernel/doc/developer_guide.dox 2009-01-11 23:36:27 UTC > (rev 1155) > @@ -0,0 +1,64 @@ > +/**\page devguide Guide for Developers > + > +Developers should familiarize themselves which the guidelines > presented in this page. > + > +\section policies Policies > + > +Code in the IMP or IMP::core modules must compile and all IMP::core > and IMP tests must pass. Code checked into other modules should > compile or be excluded from the build system and all enabled test > should pass. > + > +All code must follow the \ref coding_conventions "IMP coding > conventions". > + > +The following sorts of changes must be announced on the <imp-dev@salilab.org > > mailing list before being made > + * changes to existing kernel or core APIs > + * removal of test cases > + * creation of a new module > + * significant additions to kernel or core > + > +It is strongly suggested that the following sorts of changes be > posted to the list > + * additions of new functionality to any part of IMP > + > +Such discussion is important so that > + * you do not duplicate work > + * others can ensure that the new interfaces are consistent with > other IMP code > + * others can make suggestions or point out problems > + * others are made aware of your contribution. > + > + > +It is strongly recommended that all methods or classes be tested in > unit tests. These unit tests consist of python code in the > modulename/test directory. Test cases also help to document the > intent of code changes, as well as making sure that the new > additions are not accidentally broken in future. > + > +\section testing Testing > + > +Each class and method should have one or more associated tests in the > +\c test directory if its module. These tests should try, as much as > +possible to provide independent verification of the correctness of > the > +C++ code. In addition, classes and methods should use the IMP_check > and > +IMP_assert macros to check the correctness of arguments and > invariants > +internally and report errors when problems are detected. > + > + > +\section modules Choosing a module for your code > + > +IMP is divided into models which group related functionality. > Generally useful functionality should be added to the core or misc > model, but large blocks of well defined functionality should > probably go in their own model. Examples of appropriate units for a > module include code for building restraints from a particular type > of experimental data such as IMP::saxs or a large piece of > functionality such as IMP::domino. Please post to the <imp-dev@salilab.org > > mailing list to discuss the placement of new code. > + > +Each module has a responsible owner or owners, and it is up to them > whether they want to allow others commit to change code in their > module. Email the imp-dev@salilab.org mailing list to discuss such > policies. > + > +If you do not want to put your code into the IMP repository, you > can just add a local module to IMP using the make-module script. > This script creates a module and hooks it into the build system. You > can then immediately add header, source and test files and have > everything work. To use the script run > +\command{./kernel/doc/bin/make-module mymodulename} > +This will create a new module called "mymodulename". > + > + > +\section submission Submission of changes to IMP kernel or IMP.core > + > +In order to submit changes to the kernel or IMP.core, you should > prepare a patch against the current svn version of IMP. To do that, > make your changes to an up to date copy of IMP and then do > +\command{svn diff paths/to/changed/files > kernel/doc/patch/ > mypatch.patch} > +to generate a description of the patch in the file "mypatch.patch". > You should then create a description of the patch in kernel/doc/ > patch/mypatch.readme and commit the two files into the repository by > doing > +\command{svn add kernel/doc/patch/mypatch*} > +\command{svn commit kernel/doc/patch/mypatch* -m "very brief > description"} > +If the patch introduces API changes, then post a short description > to the imp-dev@salilab.org mailing list. > + > +Patches should contain a related set of changes. For example, a > patch which adds a new method foo, a new testcase for foo, and some > documentation for the SpecialVector class, should be split into two > patches: one for the foo method and test, and the other for the > SpecialVector documentation. > +It is much easier for others to understand your patch's changes if > it is small and contains only relevant changes. > + > +Patches to modules can be submitted directly by doing: > +\command{svn commit -m "message describing the patch" files or > directories to submit} > +*/ > \ No newline at end of file > > Copied: trunk/kernel/doc/developers.dox (from rev 1147, trunk/kernel/ > doc/inputs/developers.dox.in) > =================================================================== > --- trunk/kernel/doc/developers.dox (rev 0) > +++ trunk/kernel/doc/developers.dox 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,20 @@ > +/** > + \page developers IMP Developers > + > + \imp developers are divided into two categories: > + - <b>contributers</b>, developers who write a module that is > included in the \imp repository > + - <b>core developers</b> who contribute code to the \imp kernel > and core and help maintain the infrastructure. > + > + Both classes of developers must follow the \ref > coding_conventions "coding conventions" and be familiar with the > contents of the \ref devguide "developers guide". > + > + \section dev_links Useful Links > + - \ref api "API documentation" > + - \ref coding_conventions "Coding conventions" > + - \salilab{internal/imp/tests.html,Daily build status} > + - \ref devguide "Developer guide" > + - \salilab{imp/bugs,Bug tracker} > + - \impdev email list. All developers should monitor this list. > The > + discussions are \salilab{imp/archives/imp-dev,archived} > + - \impcommit is an email list which received notifications > + of all changes made to the \imp svn. > +*/ > > > Property changes on: trunk/kernel/doc/developers.dox > ___________________________________________________________________ > Added: svn:mergeinfo > + > > Copied: trunk/kernel/doc/introduction.dox.in (from rev 1147, trunk/ > kernel/doc/inputs/introduction.dox.in) > =================================================================== > --- trunk/kernel/doc/introduction.dox.in > (rev 0) > +++ trunk/kernel/doc/introduction.dox.in 2009-01-11 23:36:27 UTC > (rev 1155) > @@ -0,0 +1,275 @@ > +/** > +\page introduction An Introduction to IMP > + > + > +\section i0 Architecture > + > + There are several key concepts in \imp: > + - Representation: all data is stored as attributes of an > IMP::Particle > + - \ref decorators "Decorators" ease use of the particles and help > + maintain invariants > + - Scoring: > + - a IMP::Restraint is used to compute the score of some subset > of the particles > + - IMP::ScoreState objects compute maintain high level > information about the particles (such as which particles are close > to one another) > + - an IMP::Optimizer optimizes the Particles with respect to the > Restraints > + > + > + - The IMP::Model holds the particles, restraints, and score states. > + > + > +\section i05 Restraints > + > + The scoring function for the particles is created by combining > various components. > + For example: > + > + - IMP::core::PairsRestraint applies an arbitrary IMP::PairScore to > + all the pairs of particles in a list of particles > + > + - this list of particles could be generated from an > + IMP::core::ClosePairsScoreState so that it always contains a list > + of which particles are close to one another > + > + - the IMP::PairScore could be an > IMP::core::SphereDistancePairScore, > + which scores the pair of particles on the distance between the > two > + spheres defined by the particles center and radius. > + > + - the way the IMP::core::SphereDistancePairScore computes a score > + from the distance could be using an IMP::core::HarmonicLowerBound > + so that the particles are repelled. > + > + > +\section i5 Other important bits > +There is good \ref log "logging support": > +\code > +IMP::set_log_level(IMP.VERBOSE); > +IMP_LOG(TERSE, "Something interesting has occurred with variable " > + << var << std::endl); > +\endcode > + > +\ref assert "Error reporting/checking" which can be controlled at > runtime > +\code > +IMP::set_check_level(IMP.EXPENSIVE); > +IMP_check(boolean_condition, "An error has occurred with value " > + << some_value, > + ExceptionType); > +\endcode > + > +The control functions are accessible from Python, but the check and > log macros are not. > + > +Saving state > +\htmlonly > +IMP_PYTHON(fragments/read_write) > +\endhtmlonly > + > +\verbatim > +IMP::core::write(my_imp_model, "somefile"); > +IMP::core::read("somefile", my_imp_model); > +\endverbatim > + > + > + > +\section i6 Examples > +The following examples all are in python and C++ The following code > is ommitted from the examples: > +\htmlonly > +IMP_PYTHON(fragments/setup) > +\endhtmlonly > + > +\code > +#include <IMP.h> > +#include <IMP/core.h> > + > +IMP::PointerIMP::Model m= new IMP::Model(); > +IMP::core::SingletonContainer ps; > +for (int i=0; i< 100; ++i) { > + IMP::Particle* p=new IMP::Particle(); > + ps->add_particle(p); > + m->add_particles(p); > + IMP::core::XYZRDecorator d= IMP::core::XYZRDecorator::create(p); > + d.set_coordinates_are_optimized(true); > + d.set_coordinates(IMP::random_vector_in_box()); > + d.set_radius(1.0); > +} > + > +\endcode > + > + > + > + > + > +\section i7 Restraint some distances > + > +Restrain the distance between the first two particles. > + > +\htmlonly > +IMP_PYTHON(fragments/pair_restraint) > +\endhtmlonly > + > + > +\code > +IMP::core::Harmonic *uf= new IMP::core::Harmonic(0,1); > +IMP::core::SphereDistancePairScore *df= new > IMP::core::SphereDistancePairScore(uf); > +IMP::core::PairRestraint* r= new IMP::core::PairRestraint(df, ps- > >get_particle(0), ps->get_particle(1)); > +m->add_restraint(r); > +\endcode > + > + > + > +\section i8 Preventing collisions > +The ClosePairsScoreState maintains a list of all pairs of particles > which contains all pairs closer than min distance (between the > spheres). The HarmonicLowerBound forces the spheres apart. > +\htmlonly > +IMP_PYTHON(fragments/excluded_volume) > +\endhtmlonly > + > +\code > +IMP::core::ClosePairsScoreState *nbl= new > IMP::core::ClosePairsScoreState(ps); > +nbl->set_distance(min_distance) > +m->add_score_state(nbl); > +IMP::core::HarmonicLowerBound* h= new > IMP::core::HarmonicLowerBound(0,1); > +IMP::core::SphereDistancePairScore *sd= new > IMP::core::SphereDistancePairScore(h); > +IMP::core::SingletonsRestraint* nbr= new > IMP::core::SingletonsRestraint(sd, nbl->get_close_pairs_container()); > +m->add_restraint(nbr); > +\endcode > + > + > + > + > + > + > + > +\section i9 Restraining bonds > + > +Load a protein and restrain all the bonds to have the correct > length. Bond angles is a bit trickier at the moment. > + > +\htmlonly > +IMP_PYTHON(fragments/load_protein_restrain_bonds) > +\endhtmlonly > + > +\code > +// Currently you can't read a pdb from C++ > +IMP::core::MolecularHierarchyDecorator prot=???; > +IMP::core::BondDecorators bds= IMP::core::get_internal_bonds(prot); > +IMP::Particles ps(bds.size()); > +for (unsigned int i=0; i< bds.size(); ++i) ps[i]= > bds[i].get_particle(); > +IMP::core::ListSingletonContainer *bl= new > IMP::core::ListSingletonContainer(ps); > +IMP::core::Harmonic *h= new IMP::core::Harmonic(0,1); > +IMP::core::BondDecoratorSingletonScore* bs= new > IMP::core::BondDecoratorSingletonScore(h); > +IMP::core::SingletonsRestraint *br= new > IMP::core::SingletonsRestraint(bs, bl); > +m->add_restraint(br); > +\endcode > + > + > + > + > + > + > + > +\section i10 Simple optimization setup > +A basic setup for optimizing a model. > +\htmlonly > +IMP_PYTHON(fragments/basic_optimization) > +\endhtmlonly > + > +\code > +IMP::PointerIMP::Model m= new IMP::Model(); > +IMP::Particles particles = setup_model(m); > + > +std::string best; > +float best_score=std::numeric_limitsIMP::Float::infinity(); > + > +IMP::core::ConjugateGradients o; > +o.set_model(m) > +for (int i=0; i< 100; ++i) { > + randomize(particles) > + IMP::Float score=o.optimize(1000) > + if (score < best_score) { > + std::ostringstream oss; > + IMP::core::write(m, oss); > + best=oss.str(); > + best_score= score; > + } > +} > +std::istringstream iss(best_score); > +IMP::core::read(iss, m); > +\endcode > + > +\section i11 Writing a simple restraint > +This is actually an IMP::core::SingletonsRestraint. You really > wouldn't want to write such a thing in Python, although you can. > + > +\code > +class IMPDLLEXPORT MyRestraint: public IMP::Restraint { > + IMP::PointerIMP::SingletonScore ss_; > + IMP::PointerIMP::core::SingletonContainer sc_; > +public: > + MyRestraint(IMP::SingletonScore *ss, > + IMP::core::SingletonContainer *sc): ss_(ss), > + sc_(sc){} > + IMP_RESTRAINT(my_version_info); > +}; > + > +IMP::Float MyRestraint::evaluate(IMP::DerivativeAccumulator *da) { > + IMP::Float accum=0; > + for (IMP::core::SingletonContainer::ParticlesIterator it = > sc_->particles_begin(); > + it != sc_->particles_end(); ++it) { > + accum += ss_->evaluate(*it, da); > + } > + return accum; > +} > +IMP::Float MyRestraint::show(std::ostream &out) const { > + out << "MyRestraint on " << sc_->get_number_of_particles() << > " particles" << std::endl; > +} > + > +IMP::ParticlesList > +MyRestraint::get_interacting_particles() const > +{ > + return IMP::ParticlesList(); > +} > + > +\endcode > + > + > +\section i12 Available functionality > + > +Look through the types inherited from these methods to get an idea > of the functionality available. > + > +- IMP::DecoratorBase > +- IMP::Restraint > +- IMP::SingletonScore > +- IMP::PairScore > +- IMP::TripletScore > +- and check out the modules page for an orthogonal view > + > + > + > + > +\section i13 C++ vs Python > + > +Most code maps trivially from one to the other as you can see in > the example. > +- have to declare variables in C++ > +- need to know about smart pointers (use IMP::Pointer to store > pointers) > +- memory management is a bit of a mess in Python > +- a few things can only be done in one language or the other (pdb > files in python) > + > +Debugging is much easier in C++. > +- hard to inspect objects in python > + > +Easier to experiment in Python. > +- we don't have good doc strings though and no str(foo) > + > +Recommendations: > +- write restraints and decorators in C++ > +- never inherit from a C++ object in Python: the python wrapper we > use does not manage memory properly. > + > + > + > +\section i15 Getting started > + > +The easiest way to get started developing with \imp is to use a > local module. > +To do this run the \command{./kernel/doc/bin/make-module my_module} > in the > +main \imp directory. This will create a new module in modules/ > my_module. See > +\ref make_module "Making a module" for more information. > + > +You should then read the > + - \ref api "API documentation" > + - and \ref coding_conventions "Coding conventions" > + > +*/ > > Copied: trunk/kernel/doc/main.dox (from rev 1147, trunk/kernel/doc/ > inputs/main.dox.in) > =================================================================== > --- trunk/kernel/doc/main.dox (rev 0) > +++ trunk/kernel/doc/main.dox 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,37 @@ > +/** > + \mainpage IMP Documentation > + > + Welcome to the \imp documentation. If you are not familiar with > \imp, you > + should read our \ref introduction "Introduction to IMP". For help > installing > + \imp read the \wiki{installation, installation instructions}. > + > + The important documentation can be found in: > + - \ref api "API Documentation" > + - \ref examples "Examples" > + - \wiki{FrontPage,IMP wiki} > + - \wiki{FAQ, FAQ} > + > + If you encounter a bug or would like a new feature, please report > it in the > + \salilab{imp/bugs,Bug Tracker}. > + > + Information for developers and prospective contributes to \imp can > be found > + on the \ref developers "Developers page". > + > + \section new What's new in IMP? > + > + - a script to \ref make_module "create a new module" to help you > get started > + quickly. > + > + - replacements for the non-bonded lists: > IMP::core::ClosePairsScoreState > + and IMP::core::CloseBipartitlePairsScoreState > + > + - \salilab{imp/doc/doxygen/deprecated.html,many existing classes} > have been \ref deprecation "deprecated". > + > + */ > + > +/** > + \namespace IMP \brief The IMP library. > + > + All kernel and module classes and functions should be in this > namespace or > + a sub-namespace. > + */ > > Copied: trunk/kernel/doc/makemodule.dox (from rev 1147, trunk/kernel/ > doc/inputs/makemodule.dox.in) > =================================================================== > --- trunk/kernel/doc/makemodule.dox (rev 0) > +++ trunk/kernel/doc/makemodule.dox 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,42 @@ > +/** \page make_module Making a module > + > + This page describes how to create a new module in your local copy > + of \imp. Creating such a module is the easiest way to get started > + developing code for \imp. > + > + To get started, first pick the name of your module. Here we will > + use \string{my_module}. The name should only contain letters, > numbers and > + underscores. > + > + Then do > + \command{./kernel/doc/bin/make-module my_module} > + to create the module. > + > + You can use your new module in a variety of ways: > + - add C++ code to your module by putting \string{.h} files > + in \string{modules/my_module/include} and \string{.cpp} files > in > + \string{modules/my_module/src}. In order to use use your new > functions and > + classes in python, you must add a line > + \string{%include "IMP/my_module/myheader.h"} near the end of > the file > + \string{modules/my_module/pyext/my_module.i}. > + - write C++ programs using IMP by creating \string{.cpp} files in > + \string{modules/my_module/bin}. Each \string{.cpp} file > placed there > + is built into a separate executable. > + - add python code to your library by putting a \string{.py} > file in > + \string{modules/my_module/pyext/my_module/} > + - add python code to your library by by adding > + \string{%pythoncode} blocks to \string{modules/my_module/ > pyext/my_module.i}. > + - add test code to your library by putting \string{.py} files in > + \string{modules/my_module/test} or a subdirectory. > + > + Examples of all types of usage are included in the newly created > + module. > + > + If you feel your module is of interest to other \imp users and > + developers, post to the \impdev list to discuss adding > + it to the repository. > + > + If you document your code, running \command{scons doc} will build > + documentation of all of the modules including yours. To access > the > + documentation, open \string{doc/html/index.html}. > +*/ > \ No newline at end of file > > > Property changes on: trunk/kernel/doc/makemodule.dox > ___________________________________________________________________ > Added: svn:mergeinfo > + > > Modified: trunk/tools/__init__.py > =================================================================== > --- trunk/tools/__init__.py 2009-01-11 23:33:46 UTC (rev 1154) > +++ trunk/tools/__init__.py 2009-01-11 23:36:27 UTC (rev 1155) > @@ -7,6 +7,8 @@ > from SCons.Script import * > import hierarchy > import pyscanner > +import generate_doxygen > +import make_examples > import symlinks > > __all__ = ["add_common_variables", "MyEnvironment", > "get_pyext_environment", > @@ -229,7 +231,10 @@ > env.AddMethod(symlinks.LinkInstall) > env.AddMethod(symlinks.LinkInstallAs) > env.AddMethod(hierarchy.InstallHierarchy) > - env.Prepend(SCANNERS = [_SWIGScanner, pyscanner.PythonScanner]) > + env.Prepend(SCANNERS = [_SWIGScanner, pyscanner.PythonScanner], > + BUILDERS = {'GenerateDoxFromIn': > + generate_doxygen.GenerateDoxFromIn, > + 'MakeExamples': > make_examples.MakeExamples}) > if env['CC'] == 'gcc': > env.Append(CCFLAGS="-Wall -g") > if env.get('include', None) is not None: > > Copied: trunk/tools/colorize_python.py (from rev 1147, trunk/kernel/ > doc/bin/colorize_python.py) > =================================================================== > --- trunk/tools/colorize_python.py (rev 0) > +++ trunk/tools/colorize_python.py 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,117 @@ > +#!/usr/bin/python > + > +""" > + MoinMoin - Python Source Parser > +""" > + > +# Imports > +import cgi, string, sys, cStringIO > +import keyword, token, tokenize > + > + > + > ############################################################################# > +### Python Source Parser (does Hilighting) > + > ############################################################################# > + > +_KEYWORD = token.NT_OFFSET + 1 > +_TEXT = token.NT_OFFSET + 2 > + > +_colors = { > + token.NUMBER: '#0080C0', > + token.OP: '#0000C0', > + token.STRING: '#004080', > + tokenize.COMMENT: '#008000', > + token.NAME: '#000000', > + token.ERRORTOKEN: '#FF8080', > + _KEYWORD: '#C00000', > + _TEXT: '#000000', > +} > + > + > +class Parser: > + """ Send colored python source. > + """ > + > + def __init__(self, raw, out = sys.stdout): > + """ Store the source text. > + """ > + self.raw = string.strip(string.expandtabs(raw)) > + self.out = out > + > + def format(self, formatter, form): > + """ Parse and send the colored source. > + """ > + # store line offsets in self.lines > + self.lines = [0, 0] > + pos = 0 > + while 1: > + pos = string.find(self.raw, '\n', pos) + 1 > + if not pos: break > + self.lines.append(pos) > + self.lines.append(len(self.raw)) > + > + # parse the source and write it > + self.pos = 0 > + text = cStringIO.StringIO(self.raw) > + self.out.write('<pre><font face="Lucida,Courier New">') > + try: > + tokenize.tokenize(text.readline, self) > + except tokenize.TokenError, ex: > + msg = ex[0] > + line = ex[1][0] > + self.out.write("<h3>ERROR: %s</h3>%s\n" % ( > + msg, self.raw[self.lines[line]:])) > + self.out.write('</font></pre>') > + > + def __call__(self, toktype, toktext, (srow,scol), (erow,ecol), > line): > + """ Token handler. > + """ > + if 0: > + print "type", toktype, token.tok_name[toktype], "text", > toktext, > + print "start", srow,scol, "end", erow,ecol, "<br>" > + > + # calculate new positions > + oldpos = self.pos > + newpos = self.lines[srow] + scol > + self.pos = newpos + len(toktext) > + > + # handle newlines > + if toktype in [token.NEWLINE, tokenize.NL]: > + self.out.write('\n') > + return > + > + # send the original whitespace, if needed > + if newpos > oldpos: > + self.out.write(self.raw[oldpos:newpos]) > + > + # skip indenting tokens > + if toktype in [token.INDENT, token.DEDENT]: > + self.pos = newpos > + return > + > + # map token type to a color group > + if token.LPAR <= toktype and toktype <= token.OP: > + toktype = token.OP > + elif toktype == token.NAME and keyword.iskeyword(toktext): > + toktype = _KEYWORD > + color = _colors.get(toktype, _colors[_TEXT]) > + > + style = '' > + if toktype == token.ERRORTOKEN: > + style = ' style="border: solid 1.5pt #FF0000;"' > + > + # send text > + self.out.write('<font color="%s"%s>' % (color, style)) > + self.out.write(cgi.escape(toktext)) > + self.out.write('</font>') > + > + > +if __name__ == "__main__": > + import os, sys > + print "Formatting..." > + > + # open own source > + source = open(sys.argv[1]).read() > + > + # write colorized version to "python.html" > + Parser(source, open(sys.argv[2], 'wt')).format(None, None) > > Added: trunk/tools/generate_doxygen.py > =================================================================== > --- trunk/tools/generate_doxygen.py (rev 0) > +++ trunk/tools/generate_doxygen.py 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,48 @@ > +"""Generate regular Doxygen .dox files from .dox.in files, which > contain our > + own Doxygen extensions (e.g. IMP_PYTHON() to insert a colorized > + Python example).""" > + > +from SCons.Script import Dir, File, Builder, Action > +import SCons.Node.FS > +import re > +import colorize_python > + > +_example_path = Dir('#/doc/examples') > + > +exre = re.compile('IMP_PYTHON((.*))') > + > +def _action_generate_dox(target, source, env): > + fin = file(source[0].path, 'r') > + fout = file(target[0].path, 'w') > + print >> fout, "/* Do NOT edit this file directly - it is auto- > generated!" > + print >> fout, " Edit %s instead */" % source[0].path > + print >> fout > + for line in fin: > + m = exre.search(line) > + if m: > + name = m.group(1) > + fullpath = _example_path.File(name + '.py') > + source = file(fullpath.path).read() > + colorize_python.Parser(source, fout).format(None, None) > + print >> fout > + else: > + fout.write(line) > + return 0 > + > +def _emit_generate_dox(target, source, env): > +# Disable the emitter for now, since the Python scanner will > currently pull > +# in all of the IMP modules as dependencies (thinking we want to > run these > +# Python files) > +# deps = exre.findall(source[0].get_contents()) > +# source.extend([_example_path.File(name + '.py') for name in > deps]) > + return (target, source) > + > +def _print_generate_dox(target, source, env): > + return "Generate '%s' from '%s')" % (target[0], source[0]) > + > +GenerateDoxFromIn = Builder(action=Action(_action_generate_dox, > + _print_generate_dox), > + suffix=".dox", > + prefix=".generated/", > + src_suffix=".dox.in", > + emitter=_emit_generate_dox) > > Added: trunk/tools/make_examples.py > =================================================================== > --- trunk/tools/make_examples.py (rev 0) > +++ trunk/tools/make_examples.py 2009-01-11 23:36:27 UTC (rev 1155) > @@ -0,0 +1,80 @@ > +import colorize_python > +from SCons.Script import Glob, Dir, File, Builder, Action > +import SCons.Node.FS > +import os > + > +example_path = Dir('#/doc/examples') > + > +def nice_name(string): > + return string.title().replace("_", " ").replace("Cxx", "C++") > + > +def find_examples(top): > + files = Glob("%s/*" % top.abspath) > + subdirs = [x for x in files if isinstance(x, SCons.Node.FS.Dir)] > + examples = [x for x in files if (x.path.endswith('py') \ > + or x.path.endswith('cpp'))] > + > + sublist = [] > + dirdescr = file(top.File('README').abspath).read() > + elist=[] > + for ex in examples: > + readme = os.path.splitext(ex.abspath)[0] + ".readme" > + edesc = file(readme).read() > + elist.append((ex, edesc)) > + sublist.append((top, dirdescr, elist)) > + for x in subdirs: > + sublist.extend(find_examples(x)) > + return sublist > + > +def write_doxygen(tree, outputname): > + for d in tree: > + path= d[0].path > + name= os.path.split(path)[1] > + outfile= file(outputname+"/"+name+".dox", 'w') > + outfile.write("/**\n") > + > + descr= d[1] > + if name == "": wname="Examples" > + else: wname=name > + outfile.write("\page "+wname+ " " + nice_name(wname) +"\n\n") > + outfile.write(descr+"\n\n") > + # find subpages > + for dp in tree: > + pth = dp[0].path > + parent= os.path.split(os.path.split(pth)[0])[1] > + if parent is name and pth is not name: > + outfile.write("\subpage "+os.path.split(pth)[1]+"\n > \n") > + > + #print d > + for e in d[2]: > + pth = e[0].path > + nm= os.path.splitext(os.path.split(pth)[1])[0] > + path=os.path.splitext(pth)[0] > + outfile.write("\section " +nm + " " + nice_name(nm)+"\n > \n") > + outfile.write(e[1]+"\n\n") > + if pth.endswith('py'): > + outfile.write("\htmlonly\n") > + colorize_python.Parser(file(pth).read(), > + outfile).format(None, None) > + outfile.write("\endhtmlonly\n\n") > + else: > + outfile.write("\include "+nm+".cpp\n\n") > + outfile.write("*/\n") > + > + > +def _action_make_examples(target, source, env): > + tree = find_examples(example_path) > + write_doxygen(tree, os.path.dirname(target[0].path)) > + > +def _emit_make_examples(target, source, env): > + tree = find_examples(example_path) > + dir = Dir(os.path.dirname(target[0].abspath)) > + target = [dir.File(os.path.split(x[0].path)[1] + '.dox') for x > in tree] > + return (target, source) > + > +def _print_make_examples(target, source, env): > + print "Generating doxygen pages for examples" > + > +MakeExamples = Builder(action=Action(_action_make_examples, > + _print_make_examples), > + emitter=_emit_make_examples) > > _______________________________________________ > IMP-commits mailing list > IMP-commits@salilab.org > https://salilab.org/mailman/listinfo/imp-commits