Merge pull request #744 from akohlmey/doc-update

Documentation build updates

doc/Makefile

@@ -20,6 +20,7 @@ ifeq ($(shell which virtualenv >/dev/null 2>&1; echo $$?), 0)
 HAS_VIRTUALENV = YES
 endif
 
+SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
 SOURCES=$(wildcard src/*.txt)
 OBJECTS=$(SOURCES:src/%.txt=$(RSTDIR)/%.rst)
 
@@ -55,7 +56,7 @@ html: $(OBJECTS) $(ANCHORCHECK)
 	@(\
 		. $(VENV)/bin/activate ;\
 		cp -r src/* $(RSTDIR)/ ;\
-		sphinx-build -j 8 -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
+		sphinx-build $(SPHINXEXTRA) -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
 		echo "############################################" ;\
 		doc_anchor_check src/*.txt ;\
 		echo "############################################" ;\
@@ -91,7 +92,7 @@ epub: $(OBJECTS)
 	@(\
 		. $(VENV)/bin/activate ;\
 		cp -r src/* $(RSTDIR)/ ;\
-		sphinx-build -j 8 -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
+		sphinx-build $(SPHINXEXTRA) -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
 		deactivate ;\
 	)
 	@mv  epub/LAMMPS.epub .
@@ -159,7 +160,7 @@ $(VENV):
 	@( \
 		virtualenv -p $(PYTHON) $(VENV); \
 		. $(VENV)/bin/activate; \
-		pip install Sphinx==1.5.6; \
+		pip install Sphinx; \
 		pip install sphinxcontrib-images; \
 		deactivate;\
 	)

doc/src/Section_howto.txt

@@ -454,7 +454,7 @@ NOTE: By default, for 2d systems, granular particles are still modeled
 as 3d spheres, not 2d discs (circles), meaning their moment of inertia
 will be the same as in 3d.  If you wish to model granular particles in
 2d as 2d discs, see the note on this topic in "Section
-6.2"_Section_howto.html#howto_2, where 2d simulations are disussed.
+6.2"_Section_howto.html#howto_2, where 2d simulations are discussed.
 
 :line
 

doc/src/Section_packages.txt

@@ -243,7 +243,7 @@ COLLOID package :link(COLLOID),h4
 
 [Contents:]
 
-Coarse-grained finite-size colloidal particles.  Pair stayle and fix
+Coarse-grained finite-size colloidal particles.  Pair styles and fix
 wall styles for colloidal interactions.  Includes the Fast Lubrication
 Dynamics (FLD) method for hydrodynamic interactions, which is a
 simplified approximation to Stokesian dynamics.
@@ -734,7 +734,7 @@ make lib-latte args="-b -m gfortran"    # download and build in lib/latte and
 Note that 3 symbolic (soft) links, "includelink" and "liblink" and
 "filelink", are created in lib/latte to point into the LATTE home dir.
 When LAMMPS builds in src it will use these links.  You should 
-also check that the Makefile.lammps file you create is apporpriate
+also check that the Makefile.lammps file you create is appropriate
 for the compiler you use on your system to build LATTE.
 
 You can then install/un-install the package and build LAMMPS in the
@@ -984,7 +984,7 @@ MSCG package :link(mscg),h4
 [Contents:]
 
 A "fix mscg"_fix_mscg.html command which can parameterize a
-Mulit-Scale Coarse-Graining (MSCG) model using the open-source "MS-CG
+Multi-Scale Coarse-Graining (MSCG) model using the open-source "MS-CG
 library"_mscg_home.
 
 :link(mscg_home,https://github.com/uchicago-voth/MSCG-release)
@@ -1781,7 +1781,7 @@ coarse-grained DPD-based models for energetic, reactive molecular
 crystalline materials.  It includes many pair styles specific to these
 systems, including for reactive DPD, where each particle has internal
 state for multiple species and a coupled set of chemical reaction ODEs
-are integrated each timestep.  Highly accurate time intergrators for
+are integrated each timestep.  Highly accurate time integrators for
 isothermal, isoenergetic, isobaric and isenthalpic conditions are
 included.  These enable long timesteps via the Shardlow splitting
 algorithm.
@@ -2231,7 +2231,7 @@ Several extensions of the the dissipative particle dynamics (DPD)
 method.  Specifically, energy-conserving DPD (eDPD) that can model
 non-isothermal processes, many-body DPD (mDPD) for simulating
 vapor-liquid coexistence, and transport DPD (tDPD) for modeling
-advection-diffuion-reaction systems. The equations of motion of these
+advection-diffusion-reaction systems. The equations of motion of these
 DPD extensions are integrated through a modified velocity-Verlet (MVV)
 algorithm.
 
@@ -2495,7 +2495,7 @@ make machine :pre
 
 NOTE: The LAMMPS executable these steps produce is not yet functional
 for a QM/MM simulation.  You must also build Quantum ESPRESSO and
-create a new executable which links LAMMPS and Quanutm ESPRESSO
+create a new executable which links LAMMPS and Quantum ESPRESSO
 together.  These are steps 3 and 4 described in the lib/qmmm/README
 file.
 
@@ -2554,7 +2554,7 @@ developed by the Cambridge University group.
 
 :link(quip,https://github.com/libAtoms/QUIP)
 
-To use this package you must have the QUIP libAatoms library available
+To use this package you must have the QUIP libAtoms library available
 on your system.
 
 [Author:] Albert Bartok (Cambridge University)
@@ -2809,7 +2809,7 @@ USER-VTK package :link(USER-VTK),h4
 
 A "dump vtk"_dump_vtk.html command which outputs snapshot info in the
 "VTK format"_vtk, enabling visualization by "Paraview"_paraview or
-other visuzlization packages.
+other visualization packages.
 
 :link(vtk,http://www.vtk.org)
 :link(paraview,http://www.paraview.org)

doc/src/Section_start.txt

@@ -79,7 +79,7 @@ This section has the following sub-sections:
 
 Read this first :h5,link(start_2_1)
 
-If you want to avoid building LAMMPS yourself, read the preceeding
+If you want to avoid building LAMMPS yourself, read the preceding
 section about options available for downloading and installing
 executables.  Details are discussed on the "download"_download page.
 
@@ -252,7 +252,7 @@ re-compile, after typing "make clean" (which will describe different
 clean options).
 
 The LMP_INC variable is used to include options that turn on ifdefs
-within the LAMMPS code.  The options that are currently recogized are:
+within the LAMMPS code.  The options that are currently recognized are:
 
 -DLAMMPS_GZIP
 -DLAMMPS_JPEG
@@ -363,7 +363,7 @@ installed on your platform.  If MPI is installed on your system in the
 usual place (under /usr/local), you also may not need to specify these
 3 variables, assuming /usr/local is in your path.  On some large
 parallel machines which use "modules" for their compile/link
-environements, you may simply need to include the correct module in
+environments, you may simply need to include the correct module in
 your build environment, before building LAMMPS.  Or the parallel
 machine may have a vendor-provided MPI which the compiler has no
 trouble finding.
@@ -431,7 +431,7 @@ use the KISS library described above.
 You may also need to set the FFT_INC, FFT_PATH, and FFT_LIB variables,
 so the compiler and linker can find the needed FFT header and library
 files.  Note that on some large parallel machines which use "modules"
-for their compile/link environements, you may simply need to include
+for their compile/link environments, you may simply need to include
 the correct module in your build environment.  Or the parallel machine
 may have a vendor-provided FFT library which the compiler has no
 trouble finding.  See the src/MAKE/OPTIONS/Makefile.fftw file for an
@@ -470,7 +470,7 @@ precision.
 
 The FFT_INC variable also allows for a -DFFT_SINGLE setting that will
 use single-precision FFTs with PPPM, which can speed-up long-range
-calulations, particularly in parallel or on GPUs.  Fourier transform
+calculations, particularly in parallel or on GPUs.  Fourier transform
 and related PPPM operations are somewhat insensitive to floating point
 truncation errors and thus do not always need to be performed in
 double precision.  Using the -DFFT_SINGLE setting trades off a little
@@ -483,7 +483,7 @@ with support for single-precision, as explained above.  For FFTW3 you
 also need to include -lfftw3f with the FFT_LIB setting, in addition to
 -lfftw3.  For FFTW2, you also need to specify -DFFT_SIZE with the
 FFT_INC setting and -lsfftw with the FFT_LIB setting (in place of
--lfftw).  Similarly, if FFTW2 has been preinstalled with an explicit
+-lfftw).  Similarly, if FFTW2 has been pre-installed with an explicit
 double-precision library (libdfftw.a and not the default libfftw.a),
 then you can specify -DFFT_SIZE (and not -DFFT_SINGLE), and specify
 -ldfftw to use double-precision FFTs.
@@ -714,7 +714,7 @@ list various make commands that can be used to manage packages.
 If you use a command in a LAMMPS input script that is part of a
 package, you must have built LAMMPS with that package, else you will
 get an error that the style is invalid or the command is unknown.
-Every command's doc page specfies if it is part of a package.  You can
+Every command's doc page specifies if it is part of a package.  You can
 type
 
 lmp_machine -h :pre
@@ -859,7 +859,7 @@ details for each package.
 [External libraries:]
 
 Packages in the tables "Section 4"_Section_packages.html with an "ext"
-in the last column link to exernal libraries whose source code is not
+in the last column link to external libraries whose source code is not
 included with LAMMPS.  You must first download and install the library
 before building LAMMPS with that package installed.  E.g. the voronoi
 package links to the freely available "Voro++ library"_voro_home2.  You
@@ -963,7 +963,7 @@ src/MAKE/Makefile.foo and perform the build in the directory
 Obj_shared_foo.  This is so that each file can be compiled with the
 -fPIC flag which is required for inclusion in a shared library.  The
 build will create the file liblammps_foo.so which another application
-can link to dyamically.  It will also create a soft link liblammps.so,
+can link to dynamically.  It will also create a soft link liblammps.so,
 which will point to the most recently built shared library.  This is
 the file the Python wrapper loads by default.
 
@@ -1329,8 +1329,8 @@ LAMMPS is compiled with CUDA=yes.
 numa Nm :pre
 
 This option is only relevant when using pthreads with hwloc support.
-In this case Nm defines the number of NUMA regions (typicaly sockets)
+In this case Nm defines the number of NUMA regions (typically sockets)
-on a node which will be utilizied by a single MPI rank.  By default Nm
+on a node which will be utilized by a single MPI rank.  By default Nm
 = 1.  If this option is used the total number of worker-threads per
 MPI rank is threads*numa.  Currently it is always almost better to
 assign at least one MPI rank per NUMA region, and leave numa set to
@@ -1394,7 +1394,7 @@ replica runs on on one or a few processors.  Note that with MPI
 installed on a machine (e.g. your desktop), you can run on more
 (virtual) processors than you have physical processors.
 
-To run multiple independent simulatoins from one input script, using
+To run multiple independent simulations from one input script, using
 multiple partitions, see "Section 6.4"_Section_howto.html#howto_4
 of the manual.  World- and universe-style "variables"_variable.html
 are useful in this context.
@@ -1673,7 +1673,7 @@ The first section provides a global loop timing summary. The {loop time}
 is the total wall time for the section.  The {Performance} line is
 provided for convenience to help predicting the number of loop
 continuations required and for comparing performance with other,
-similar MD codes.  The {CPU use} line provides the CPU utilzation per
+similar MD codes.  The {CPU use} line provides the CPU utilization per
 MPI task; it should be close to 100% times the number of OpenMP
 threads (or 1 of no OpenMP). Lower numbers correspond to delays due
 to file I/O or insufficient thread utilization.

doc/src/accelerate_intel.txt

@@ -78,7 +78,7 @@ order of operations compared to LAMMPS without acceleration:
 Neighbor lists can be created in a different order :ulb,l
 Bins used for sorting atoms can be oriented differently :l
 The default stencil order for PPPM is 7. By default, LAMMPS will
-calculate other PPPM parameters to fit the desired acuracy with
+calculate other PPPM parameters to fit the desired accuracy with
 this order :l
 The {newton} setting applies to all atoms, not just atoms shared
 between MPI tasks :l

doc/src/compute_cluster_atom.txt

@@ -28,7 +28,7 @@ compute 1 all aggregate/atom 3.5 :pre
 
 [Description:]
 
-Define a computation that assigns each atom a cluster, fragement,
+Define a computation that assigns each atom a cluster, fragment,
 or aggregate ID.
 
 A cluster is defined as a set of atoms, each of which is within the
@@ -53,7 +53,7 @@ like micelles.
 Only atoms in the compute group are clustered and assigned cluster
 IDs. Atoms not in the compute group are assigned a cluster ID = 0.
 For fragments, only bonds where [both] atoms of the bond are included
-in the compute group are assigned to fragments, so that only fragmets
+in the compute group are assigned to fragments, so that only fragments
 are detected where [all] atoms are in the compute group. Thus atoms
 may be included in the compute group, yes still have a fragment ID of 0.
 

doc/src/compute_pressure_uef.txt

@@ -47,7 +47,7 @@ or "fix npt/uef"_fix_nh_uef.html is active.
 
 The kinetic contribution to the pressure tensor
 will be accurate only when
-the compute specificed by {temp-ID} is a 
+the compute specified by {temp-ID} is a
 "compute temp/uef"_compute_temp_uef.html.
 
 [Related commands:]

doc/src/fix_halt.txt

@@ -64,10 +64,10 @@ not performed once every {N} steps by this command.  Instead it is
 performed (typically) only a small number of times and the elapsed
 times are used to predict when the end-of-the-run will be.  Both of
 these attributes can be useful when performing benchmark calculations
-for a desired length of time with minmimal overhead.  For example, if
+for a desired length of time with minimal overhead.  For example, if
 a run is performing 1000s of timesteps/sec, the overhead for syncing
 the timer frequently across a large number of processors may be
-non-negligble.
+non-negligible.
 
 Equal-style variables evaluate to a numeric value.  See the
 "variable"_variable.html command for a description.  They calculate
@@ -125,7 +125,7 @@ to the screen and logfile when the halt condition is triggered.  If
 {message} is set to yes, a one line message with the values that
 triggered the halt is printed.  If {message} is set to no, no message
 is printed; the run simply exits.  The latter may be desirable for
-post-processing tools that extract thermodyanmic information from log
+post-processing tools that extract thermodynamic information from log
 files.
 
 [Restart, fix_modify, output, run start/stop, minimize info:]

doc/src/fix_mvv_dpd.txt

@@ -44,7 +44,7 @@ the velocity for the force evaluation:
 
 where the parameter <font size="4">&lambda;</font> depends on the
 specific choice of DPD parameters, and needs to be tuned on a
-case-by-case basis.  Specification of a {lambda} value is opttional.
+case-by-case basis.  Specification of a {lambda} value is optional.
 If specified, the setting must be from 0.0 to 1.0.  If not specified,
 a default value of 0.5 is used, which effectively reproduces the
 standard velocity-Verlet (VV) scheme.  For more details, see

doc/src/fix_neb.txt

@@ -113,9 +113,9 @@ keeping the replicas equally spaced.
 
 :line
 
-The keyword {perp} specifies if and how a perpendicual nudging force
+The keyword {perp} specifies if and how a perpendicular nudging force
 is computed.  It adds a spring force perpendicular to the path in
-order to prevent the path from becoming too kinky.  It can
+order to prevent the path from becoming too strongly kinked.  It can
 significantly improve the convergence of the NEB calculation when the
 resolution is poor.  I.e. when few replicas are used; see
 "(Maras)"_#Maras1 for details.

doc/src/neb.txt

@@ -322,9 +322,9 @@ the fix neb command.
 The forward (reverse) energy barrier is the potential energy of the
 highest replica minus the energy of the first (last) replica.
 
-Supplementary informations for all replicas can be printed out to the
+Supplementary information for all replicas can be printed out to the
-screen and master log.lammps file by adding the verbose keyword. These
+screen and master log.lammps file by adding the verbose keyword. This
-informations include the following.  The "path angle" (pathangle) for
+information include the following.  The "path angle" (pathangle) for
 the replica i which is the angle between the 3N-length vectors (Ri-1 -
 Ri) and (Ri+1 - Ri) (where Ri is the atomic coordinates of replica
 i). A "path angle" of 180 indicates that replicas i-1, i and i+1 are
@@ -339,8 +339,8 @@ energy gradient of image i.  ReplicaForce is the two-norm of the
 3N-length force vector (including nudging forces) for replica i.
 MaxAtomForce is the maximum force component of any atom in replica i.
 
-When a NEB calculation does not converge properly, these suplementary
+When a NEB calculation does not converge properly, the suplementary
-informations can help understanding what is going wrong. For instance
+information can help understanding what is going wrong. For instance
 when the path angle becomes accute the definition of tangent used in
 the NEB calculation is questionable and the NEB cannot may diverge
 "(Maras)"_#Maras2.

doc/utils/converters/lammpsdoc/txt2rst.py

@@ -148,15 +148,18 @@ class RSTFormatting(Formatting):
         return "\n----------\n\n" + content.strip()
 
     def image(self, content, file, link=None):
-        if link and (link.lower().endswith('.jpg') or
+        # 2017-12-07: commented out to disable thumbnail processing due to dropping
-                         link.lower().endswith('.jpeg') or
+        #             support for obsolete sphinxcontrib.images extension
-                         link.lower().endswith('.png') or
+        #
-                         link.lower().endswith('.gif')):
+        #if link and (link.lower().endswith('.jpg') or
-            converted = ".. thumbnail:: " + self.markup.unescape_rst_chars(link) + "\n"
+        #                 link.lower().endswith('.jpeg') or
-        else:
+        #                 link.lower().endswith('.png') or
-            converted = ".. image:: " + self.markup.unescape_rst_chars(file) + "\n"
+        #                 link.lower().endswith('.gif')):
-            if link:
+        #    converted = ".. thumbnail:: " + self.markup.unescape_rst_chars(link) + "\n"
-                converted += "   :target: " + self.markup.unescape_rst_chars(link) + "\n"
+        #else:
+        converted = ".. image:: " + self.markup.unescape_rst_chars(file) + "\n"
+        if link:
+            converted += "   :target: " + self.markup.unescape_rst_chars(link) + "\n"
 
         if "c" in self.current_command_list:
             converted += "   :align: center\n"

doc/utils/sphinx-config/conf.py

@@ -31,8 +31,11 @@ import os
 # ones.
 extensions = [
     'sphinx.ext.mathjax',
-    'sphinxcontrib.images',
 ]
+# 2017-12-07: commented out, since this package is broken with Sphinx 16.x
+#             yet we can no longer use Sphinx 15.x, since that breaks with
+#             newer version of the multiprocessor module.
+#    'sphinxcontrib.images',
 
 images_config = {
   'default_image_width' : '25%',