"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:
# 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()
# 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
-# 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")
-
+ 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
+ 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
+ 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).
+*/
+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.
+ */
+
+ 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
@@ -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 <
> 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 <
> 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 <> 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 <> 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}
===================================================================
--- 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".
+ - \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
+
@@ -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.
+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.
+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());
+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);
+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"
+
+*/
+ 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".
===================================================================
--- 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
+# 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