Move to actively maintained dependencies for API docs (#3201)

* Proof of concept matching current behaviour with Breathe

* Reorganise C++ API docs to work without autosummary

* Revert to Sphinx-native search

* Move remaining pip deps to conda

* Remove unnecessary lunrsearch templates

* Remove lunrsearch from cmake

* Tidy up layout of API docs

* Get code blocks to work with Breathe

Breathe doesn't seem to support the Doxygen <preformatted> tag.
It does support the <code> tag, but better yet it supports using
<verbatim> tags to embed rst into docstrings. This commit changes
all <pre> tags to use RST verbatim, and updates the Python
documentation machinery to support it too.

* Clarified some language

* Have doxygen exclude undocumented classes and have sphinx fail on warnings for C++ API docs

* List custom forces and integrators last

* Add breathe to documentation CI

* Typo

* Fix link to custom forces in extras.rst

* Have Breathe process only public classes

* Strip OpenMM:: prefix from rst files to avoid colons in links

* Remove existing private classes from EXCLUDE_SYMBOLS

* Add comment to C++ cmake describing why we promote warnings to errors

* Revise documentation build instructions for new dependencies

openmmapi/include/openmm/CompoundIntegrator.h

@@ -43,28 +43,37 @@ namespace OpenMM {
  * switching back and forth between them.  To use it, create whatever other Integrators
  * you need, then add all of them to a CustomIntegrator:
  * 
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    CompoundIntegrator compoundIntegrator;
  *    compoundIntegrator.addIntegrator(new VerletIntegrator(0.001));
  *    compoundIntegrator.addIntegrator(new LangevinIntegrator(300.0, 1.0, 0.001));
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * Next create a Context, specifying the CompoundIntegrator as the Integrator to use for
  * the Context:
  * 
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *     Context context(system, compoundIntegrator);
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * Finally, call setCurrentIntegrator() to set which Integrator is active.  That one will
  * be used for all calls to step() until the next time you change it.
  * 
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *     compoundIntegrator.setCurrentIntegrator(0);
  *     compoundIntegrator.step(1000); // Take 1000 steps of Verlet dynamics
  *     compoundIntegrator.setCurrentIntegrator(1);
  *     compoundIntegrator.step(1000); // Take 1000 steps of Langevin dynamics
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * When switching between integrators, it is important to make sure they are compatible with
  * each other, and that they will interpret the positions and velocities in the same way.

openmmapi/include/openmm/CustomAngleForce.h

@@ -55,14 +55,22 @@ namespace OpenMM {
  *
  * As an example, the following code creates a CustomAngleForce that implements a harmonic potential:
  *
- * <tt>CustomAngleForce* force = new CustomAngleForce("0.5*k*(theta-theta0)^2");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomAngleForce* force = new CustomAngleForce("0.5*k*(theta-theta0)^2");
+ *
+ * \endverbatim
  *
  * This force depends on two parameters: the spring constant k and equilibrium angle theta0.  The following code defines these parameters:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    force->addPerAngleParameter("k");
  *    force->addPerAngleParameter("theta0");
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * This class also has the ability to compute derivatives of the potential energy with respect to global parameters.
  * Call addEnergyParameterDerivative() to request that the derivative with respect to a particular parameter be

openmmapi/include/openmm/CustomBondForce.h

@@ -55,14 +55,22 @@ namespace OpenMM {
  *
  * As an example, the following code creates a CustomBondForce that implements a harmonic potential:
  *
- * <tt>CustomBondForce* force = new CustomBondForce("0.5*k*(r-r0)^2");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomBondForce* force = new CustomBondForce("0.5*k*(r-r0)^2");
+ *
+ * \endverbatim
  *
  * This force depends on two parameters: the spring constant k and equilibrium distance r0.  The following code defines these parameters:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    force->addPerBondParameter("k");
  *    force->addPerBondParameter("r0");
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * This class also has the ability to compute derivatives of the potential energy with respect to global parameters.
  * Call addEnergyParameterDerivative() to request that the derivative with respect to a particular parameter be

openmmapi/include/openmm/CustomCentroidBondForce.h

@@ -86,7 +86,9 @@ namespace OpenMM {
  * As an example, the following code creates a CustomCentroidBondForce that implements a harmonic force between the
  * centers of mass of two groups of particles.
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    CustomCentroidBondForce* force = new CustomCentroidBondForce(2, "0.5*k*distance(g1,g2)^2");
  *    force->addPerBondParameter("k");
  *    force->addGroup(particles1);
@@ -97,7 +99,8 @@ namespace OpenMM {
  *    vector<double> bondParameters;
  *    bondParameters.push_back(k);
  *    force->addBond(bondGroups, bondParameters);
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * This class also has the ability to compute derivatives of the potential energy with respect to global parameters.
  * Call addEnergyParameterDerivative() to request that the derivative with respect to a particular parameter be
@@ -115,7 +118,12 @@ namespace OpenMM {
  * This enables more flexible geometric calculations.  For example, the following computes the distance
  * from group g1 to the midpoint between groups g2 and g3.
  * 
- * <tt>CustomCentroidBondForce* force = new CustomCentroidBondForce(3, "pointdistance(x1, y1, z1, (x2+x3)/2, (y2+y3)/2, (z2+z3)/2)");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomCentroidBondForce* force = new CustomCentroidBondForce(3, "pointdistance(x1, y1, z1, (x2+x3)/2, (y2+y3)/2, (z2+z3)/2)");
+ *
+ * \endverbatim
  *
  * In addition, you can call addTabulatedFunction() to define a new function based on tabulated values.  You specify the function by
  * creating a TabulatedFunction object.  That function can then appear in the expression.

openmmapi/include/openmm/CustomCompoundBondForce.h

@@ -77,16 +77,24 @@ namespace OpenMM {
  * is an interaction between three particles that depends on the angle formed by p1-p2-p3, and on the distance between
  * p1 and p3.
  *
- * <tt>CustomCompoundBondForce* force = new CustomCompoundBondForce(3, "0.5*(kangle*(angle(p1,p2,p3)-theta0)^2+kbond*(distance(p1,p3)-r0)^2)");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomCompoundBondForce* force = new CustomCompoundBondForce(3, "0.5*(kangle*(angle(p1,p2,p3)-theta0)^2+kbond*(distance(p1,p3)-r0)^2)");
+ *
+ * \endverbatim
  *
  * This force depends on four parameters: kangle, kbond, theta0, and r0.  The following code defines these as per-bond parameters:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    force->addPerBondParameter("kangle");
  *    force->addPerBondParameter("kbond");
  *    force->addPerBondParameter("theta0");
  *    force->addPerBondParameter("r0");
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * This class also has the ability to compute derivatives of the potential energy with respect to global parameters.
  * Call addEnergyParameterDerivative() to request that the derivative with respect to a particular parameter be
@@ -104,7 +112,12 @@ namespace OpenMM {
  * This enables more flexible geometric calculations.  For example, the following computes the distance
  * from particle p1 to the midpoint between particles p2 and p3.
  * 
- * <tt>CustomCompoundBondForce* force = new CustomCompoundBondForce(3, "pointdistance(x1, y1, z1, (x2+x3)/2, (y2+y3)/2, (z2+z3)/2)");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomCompoundBondForce* force = new CustomCompoundBondForce(3, "pointdistance(x1, y1, z1, (x2+x3)/2, (y2+y3)/2, (z2+z3)/2)");
+ *
+ * \endverbatim
  *
  * In addition, you can call addTabulatedFunction() to define a new function based on tabulated values.  You specify the function by
  * creating a TabulatedFunction object.  That function can then appear in the expression.

openmmapi/include/openmm/CustomExternalForce.h

@@ -56,16 +56,24 @@ namespace OpenMM {
  * As an example, the following code creates a CustomExternalForce that attracts each particle to a target position (x0, y0, z0)
  * via a harmonic potential:
  *
- * <tt>CustomExternalForce* force = new CustomExternalForce("k*((x-x0)^2+(y-y0)^2+(z-z0)^2)");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomExternalForce* force = new CustomExternalForce("k*((x-x0)^2+(y-y0)^2+(z-z0)^2)");
+ *
+ * \endverbatim
  *
  * This force depends on four parameters: the spring constant k and equilibrium coordinates x0, y0, and z0.  The following code defines these parameters:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    force->addGlobalParameter("k", 100.0);
  *    force->addPerParticleParameter("x0");
  *    force->addPerParticleParameter("y0");
  *    force->addPerParticleParameter("z0");
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * Special care is needed in systems that use periodic boundary conditions.  In that case, each particle really represents
  * an infinite set of particles repeating through space.  The variables x, y, and z contain the coordinates of one of those
@@ -73,7 +81,12 @@ namespace OpenMM {
  * this situation by using the function periodicdistance(x1, y1, z1, x2, y2, z2), which returns the minimum distance between
  * periodic copies of the points (x1, y1, z1) and (x2, y2, z2).  For example, the force given above would be rewritten as
  *
- * <tt>CustomExternalForce* force = new CustomExternalForce("k*periodicdistance(x, y, z, x0, y0, z0)^2");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomExternalForce* force = new CustomExternalForce("k*periodicdistance(x, y, z, x0, y0, z0)^2");
+ *
+ * \endverbatim
  *
  * Expressions may involve the operators + (add), - (subtract), * (multiply), / (divide), and ^ (power), and the following
  * functions: sqrt, exp, log, sin, cos, sec, csc, tan, cot, asin, acos, atan, atan2, sinh, cosh, tanh, erf, erfc, min, max, abs, floor, ceil, step, delta, select.  All trigonometric functions

openmmapi/include/openmm/CustomGBForce.h

@@ -82,7 +82,9 @@ namespace OpenMM {
  * This is a complicated class to use, and an example may help to clarify it.  The following code implements the OBC variant
  * of the GB/SA solvation model, using the ACE approximation to estimate surface area:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    CustomGBForce* custom = new CustomGBForce();
  *    custom->addPerParticleParameter("q");
  *    custom->addPerParticleParameter("radius");
@@ -102,7 +104,8 @@ namespace OpenMM {
  *                          CustomGBForce::SingleParticle);
  *    custom->addEnergyTerm("-138.935456*(1/soluteDielectric-1/solventDielectric)*q1*q2/f;"
  *                          "f=sqrt(r^2+B1*B2*exp(-r^2/(4*B1*B2)))", CustomGBForce::ParticlePair);
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * It begins by defining three per-particle parameters (charge, atomic radius, and scale factor) and two global parameters
  * (the dielectric constants for the solute and solvent).  It then defines a computed value "I" of type ParticlePair.  The

openmmapi/include/openmm/CustomHbondForce.h

@@ -78,15 +78,23 @@ namespace OpenMM {
  * As an example, the following code creates a CustomHbondForce that implements a simple harmonic potential
  * to keep the distance between a1 and d1, and the angle formed by a1-d1-d2, near ideal values:
  *
- * <tt>CustomHbondForce* force = new CustomHbondForce("k*(distance(a1,d1)-r0)^2*(angle(a1,d1,d2)-theta0)^2");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomHbondForce* force = new CustomHbondForce("k*(distance(a1,d1)-r0)^2*(angle(a1,d1,d2)-theta0)^2");
+ *
+ * \endverbatim
  *
  * This force depends on three parameters: k, r0, and theta0.  The following code defines these as per-donor parameters:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    force->addPerDonorParameter("k");
  *    force->addPerDonorParameter("r0");
  *    force->addPerDonorParameter("theta0");
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * Expressions may involve the operators + (add), - (subtract), * (multiply), / (divide), and ^ (power), and the following
  * functions: sqrt, exp, log, sin, cos, sec, csc, tan, cot, asin, acos, atan, atan2, sinh, cosh, tanh, erf, erfc, min, max, abs, floor, ceil, step, delta, select.  All trigonometric functions

openmmapi/include/openmm/CustomIntegrator.h

@@ -128,12 +128,15 @@ namespace OpenMM {
  * The following example uses a CustomIntegrator to implement a velocity Verlet
  * integrator:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    CustomIntegrator integrator(0.001);
  *    integrator.addComputePerDof("v", "v+0.5*dt*f/m");
  *    integrator.addComputePerDof("x", "x+dt*v");
  *    integrator.addComputePerDof("v", "v+0.5*dt*f/m");
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * The first step updates the velocities based on the current forces.
  * The second step updates the positions based on the new velocities, and the
@@ -151,7 +154,9 @@ namespace OpenMM {
  * step to tell the integrator when to do this.  The following example corrects
  * both these problems, using the RATTLE algorithm to apply constraints:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    CustomIntegrator integrator(0.001);
  *    integrator.addPerDofVariable("x1", 0);
  *    integrator.addUpdateContextState();
@@ -161,14 +166,17 @@ namespace OpenMM {
  *    integrator.addConstrainPositions();
  *    integrator.addComputePerDof("v", "v+0.5*dt*f/m+(x-x1)/dt");
  *    integrator.addConstrainVelocities();
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * CustomIntegrator can be used to implement multiple time step integrators.  The
  * following example shows an r-RESPA integrator.  It assumes the quickly changing
  * forces are in force group 0 and the slowly changing ones are in force group 1.
  * It evaluates the "fast" forces four times as often as the "slow" forces.
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    CustomIntegrator integrator(0.004);
  *    integrator.addComputePerDof("v", "v+0.5*dt*f1/m");
  *    for (int i = 0; i &lt; 4; i++) {
@@ -177,7 +185,8 @@ namespace OpenMM {
  *        integrator.addComputePerDof("v", "v+0.5*(dt/4)*f0/m");
  *    }
  *    integrator.addComputePerDof("v", "v+0.5*dt*f1/m");
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * The sequence of computations in a CustomIntegrator can include flow control in
  * the form of "if" and "while" blocks.  The computations inside an "if" block
@@ -192,11 +201,15 @@ namespace OpenMM {
  * to decide whether to accept the step, and if it is accepted, store the new
  * positions into "x".
  *
- * <tt><pre>
+ *
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    integrator.beginIfBlock("uniform < acceptanceProbability");
  *    integrator.addComputePerDof("x", "xnew");
  *    integrator.endBlock();
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * The condition in an "if" or "while" block is evaluated globally, so it may
  * only involve global variables, not per-DOF ones.  It may use any of the
@@ -214,9 +227,12 @@ namespace OpenMM {
  * following line uses a cross product to compute the angular momentum of each
  * particle and stores it into a per-DOF variable.
  * 
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    integrator.addComputePerDof("angularMomentum", "m*cross(x, v)");
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * Here are two more examples that may be useful as starting points for writing
  * your own integrators.  The first one implements the algorithm used by the
@@ -224,7 +240,9 @@ namespace OpenMM {
  * to the velocity Verlet algorithm shown above, so it only requires applying
  * constraints once in each time step.
  * 
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    CustomIntegrator integrator(dt);
  *    integrator.addPerDofVariable("x0", 0);
  *    integrator.addUpdateContextState();
@@ -233,12 +251,15 @@ namespace OpenMM {
  *    integrator.addComputePerDof("x", "x+dt*v");
  *    integrator.addConstrainPositions();
  *    integrator.addComputePerDof("v", "(x-x0)/dt");
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * The second one implements the algorithm used by the standard
  * LangevinMiddleIntegrator class.  kB is Boltzmann's constant.
  * 
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    CustomIntegrator integrator(dt);
  *    integrator.addGlobalVariable("a", exp(-friction*dt));
  *    integrator.addGlobalVariable("b", sqrt(1-exp(-2*friction*dt)));
@@ -253,7 +274,8 @@ namespace OpenMM {
  *    integrator.addComputePerDof("x1", "x");
  *    integrator.addConstrainPositions();
  *    integrator.addComputePerDof("v", "v + (x-x1)/dt");
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * Another feature of CustomIntegrator is that it can use derivatives of the
  * potential energy with respect to context parameters.  These derivatives are
@@ -280,9 +302,12 @@ namespace OpenMM {
  * As example, the following line defines the correct way to compute kinetic energy
  * when using a leapfrog algorithm:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    integrator.setKineticEnergyExpression("m*v1*v1/2; v1=v+0.5*dt*f/m");
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * The kinetic energy expression may depend on the following pre-defined variables:
  * x, v, f, m, dt.  It also may depend on user-defined global and per-DOF variables,

openmmapi/include/openmm/CustomManyParticleForce.h

@@ -85,18 +85,25 @@ namespace OpenMM {
  * As an example, the following code creates a CustomManyParticleForce that implements an Axilrod-Teller potential.  This
  * is an interaction between three particles that depends on all three distances and angles formed by the particles.
  *
- * <tt><pre>CustomManyParticleForce* force = new CustomManyParticleForce(3,
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomManyParticleForce* force = new CustomManyParticleForce(3,
  *        "C*(1+3*cos(theta1)*cos(theta2)*cos(theta3))/(r12*r13*r23)^3;"
  *        "theta1=angle(p1,p2,p3); theta2=angle(p2,p3,p1); theta3=angle(p3,p1,p2);"
  *        "r12=distance(p1,p2); r13=distance(p1,p3); r23=distance(p2,p3)");
  *    force->setPermutationMode(CustomManyParticleForce::SinglePermutation);
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * This force depends on one parameter, C.  The following code defines it as a global parameter:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    force->addGlobalParameter("C", 1.0);
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * Notice that the expression is symmetric with respect to the particles.  It only depends on the products
  * cos(theta1)*cos(theta2)*cos(theta3) and r12*r13*r23, both of which are unchanged if the labels p1, p2, and p3 are permuted.
@@ -110,11 +117,15 @@ namespace OpenMM {
  * between one central particle and other nearby particles.  An example of this is the 3-particle piece of the Stillinger-Weber
  * potential:
  *
- * <tt><pre>CustomManyParticleForce* force = new CustomManyParticleForce(3,
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomManyParticleForce* force = new CustomManyParticleForce(3,
  *        "L*eps*(cos(theta1)+1/3)^2*exp(sigma*gamma/(r12-a*sigma))*exp(sigma*gamma/(r13-a*sigma));"
-       "r12 = distance(p1,p2); r13 = distance(p1,p3); theta1 = angle(p3,p1,p2)");
+ *        "r12 = distance(p1,p2); r13 = distance(p1,p3); theta1 = angle(p3,p1,p2)");
  *    force->setPermutationMode(CustomManyParticleForce::UniqueCentralParticle);
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * When the permutation mode is set to UniqueCentralParticle, particle p1 is treated as the central particle.  For a set of
  * N particles, the expression is evaluated N times, once with each particle as p1.  The expression can therefore treat
@@ -135,14 +146,17 @@ namespace OpenMM {
  * to 0.)  For the water model, you could specify 0 for all oxygen atoms and 1 for all hydrogen atoms.  You can then
  * call setTypeFilter() to specify the list of allowed types for each of the N particles involved in an interaction:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    set&lt;int&gt; oxygenTypes, hydrogenTypes;
  *    oxygenTypes.insert(0);
  *    hydrogenTypes.insert(1);
  *    force->setTypeFilter(0, oxygenTypes);
  *    force->setTypeFilter(1, hydrogenTypes);
  *    force->setTypeFilter(2, hydrogenTypes);
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * This specifies that of the three particles in an interaction, p1 must be oxygen while p2 and p3 must be hydrogen.
  * The energy expression will only be evaluated for triplets of particles that satisfy those requirements.  It will
@@ -162,7 +176,12 @@ namespace OpenMM {
  * This enables more flexible geometric calculations.  For example, the following computes the distance
  * from particle p1 to the midpoint between particles p2 and p3.
  * 
- * <tt>CustomManyParticleForce* force = new CustomManyParticleForce(3, "pointdistance(x1, y1, z1, (x2+x3)/2, (y2+y3)/2, (z2+z3)/2)");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomManyParticleForce* force = new CustomManyParticleForce(3, "pointdistance(x1, y1, z1, (x2+x3)/2, (y2+y3)/2, (z2+z3)/2)");
+ *
+ * \endverbatim
  *
  * In addition, you can call addTabulatedFunction() to define a new function based on tabulated values.  You specify the function by
  * creating a TabulatedFunction object.  That function can then appear in the expression.

openmmapi/include/openmm/CustomNonbondedForce.h

@@ -66,14 +66,22 @@ namespace OpenMM {
  *
  * As an example, the following code creates a CustomNonbondedForce that implements a 12-6 Lennard-Jones potential:
  *
- * <tt>CustomNonbondedForce* force = new CustomNonbondedForce("4*epsilon*((sigma/r)^12-(sigma/r)^6); sigma=0.5*(sigma1+sigma2); epsilon=sqrt(epsilon1*epsilon2)");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomNonbondedForce* force = new CustomNonbondedForce("4*epsilon*((sigma/r)^12-(sigma/r)^6); sigma=0.5*(sigma1+sigma2); epsilon=sqrt(epsilon1*epsilon2)");
+ *
+ * \endverbatim
  *
  * This force depends on two parameters: sigma and epsilon.  The following code defines these as per-particle parameters:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    force->addPerParticleParameter("sigma");
  *    force->addPerParticleParameter("epsilon");
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * The expression <i>must</i> be symmetric with respect to the two particles.  It typically will only be evaluated once
  * for each pair of particles, and no guarantee is made about which particle will be identified as "particle 1".  In the

openmmapi/include/openmm/CustomTorsionForce.h

@@ -56,18 +56,31 @@ namespace OpenMM {
  *
  * As an example, the following code creates a CustomTorsionForce that implements a periodic potential:
  *
- * <tt>CustomTorsionForce* force = new CustomTorsionForce("0.5*k*(1-cos(theta-theta0))");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomTorsionForce* force = new CustomTorsionForce("0.5*k*(1-cos(theta-theta0))");
+ *
+ * \endverbatim
  *
  * This force depends on two parameters: the spring constant k and equilibrium angle theta0.  The following code defines these parameters:
  *
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    force->addPerTorsionParameter("k");
  *    force->addPerTorsionParameter("theta0");
- * </pre></tt>
+ *
+ * \endverbatim
  *
  * If a harmonic restraint is desired, it is important to be careful of the domain for theta, using an idiom like this:
  *
- * <tt>CustomTorsionForce* force = new CustomTorsionForce("0.5*k*min(dtheta, 2*pi-dtheta)^2; dtheta = abs(theta-theta0); pi = 3.1415926535");</tt>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
+ *    CustomTorsionForce* force = new CustomTorsionForce("0.5*k*min(dtheta, 2*pi-dtheta)^2; dtheta = abs(theta-theta0); pi = 3.1415926535");
+ *
+ * \endverbatim
  *
  * This class also has the ability to compute derivatives of the potential energy with respect to global parameters.
  * Call addEnergyParameterDerivative() to request that the derivative with respect to a particular parameter be

openmmapi/include/openmm/NonbondedForce.h

@@ -93,11 +93,14 @@ namespace OpenMM {
  * 
  * The "effective" parameters for a particle (those used to compute forces) are given by
  * 
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    charge = baseCharge + param*chargeScale
  *    sigma = baseSigma + param*sigmaScale
  *    epsilon = baseEpsilon + param*epsilonScale
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * where the "base" values are the ones specified by addParticle() and "oaram" is the current value
  * of the Context parameter.  A single Context parameter can apply offsets to multiple particles,

platforms/common/include/openmm/common/BondedUtilities.h

@@ -68,12 +68,15 @@ namespace OpenMM {
  * As a simple example, the following source code would be used to implement a pairwise interaction of
  * the form E=r^2:
  * 
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    real4 delta = pos2-pos1;
  *    energy += delta.x*delta.x + delta.y*delta.y + delta.z*delta.z;
  *    real3 force1 = 2.0f*delta;
  *    real3 force2 = -2.0f*delta;
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * Interactions will often depend on parameters or other data.  Call addArgument() to provide the data
  * to this class.  It will be passed to the interaction kernel as an argument, and you can refer to it

platforms/cuda/include/CudaBondedUtilities.h

@@ -68,12 +68,15 @@ class CudaContext;
  * As a simple example, the following source code would be used to implement a pairwise interaction of
  * the form E=r^2:
  * 
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    real4 delta = pos2-pos1;
  *    energy += delta.x*delta.x + delta.y*delta.y + delta.z*delta.z;
  *    real3 force1 = 2.0f*delta;
  *    real3 force2 = -2.0f*delta;
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * Interactions will often depend on parameters or other data.  Call addArgument() to provide the data
  * to this class.  It will be passed to the interaction kernel as an argument, and you can refer to it

platforms/opencl/include/OpenCLBondedUtilities.h

@@ -68,12 +68,15 @@ class OpenCLContext;
  * As a simple example, the following source code would be used to implement a pairwise interaction of
  * the form E=r^2:
  * 
- * <tt><pre>
+ * \verbatim embed:rst:leading-asterisk
+ * .. code-block:: cpp
+ *
  *    real4 delta = pos2-pos1;
  *    energy += delta.x*delta.x + delta.y*delta.y + delta.z*delta.z;
  *    real4 force1 = 2.0f*delta;
  *    real4 force2 = -2.0f*delta;
- * </pre></tt>
+ *
+ * \endverbatim
  * 
  * Interactions will often depend on parameters or other data.  Call addArgument() to provide the data
  * to this class.  It will be passed to the interaction kernel as an argument, and you can refer to it

wrappers/python/src/swig_doxygen/swigInputBuilder.py

@@ -17,7 +17,7 @@ except ImportError:
     from HTMLParser import HTMLParser
 
 INDENT = "   "
-docTags = {'emphasis':'i', 'bold':'b', 'itemizedlist':'ul', 'listitem':'li', 'preformatted':'pre', 'computeroutput':'tt', 'subscript':'sub'}
+docTags = {'emphasis':'i', 'bold':'b', 'itemizedlist':'ul', 'listitem':'li', 'preformatted':'pre', 'computeroutput':'tt', 'subscript':'sub', 'verbatim': 'verbatim'}
 
 def is_method_abstract(argstring):
     return argstring.split(")")[-1].find("=0") >= 0