suspend support for sphinxcontrib.images

the sphinxcontrib.image extension was broken with sphinx 16.x.
however, sphinx 15.x breaks with newer version of the multiprocessor module.
so we suspend the thumbnail processing and lift the lock to sphinx 15.x

also, the number of parallel sphinx tasks is can be overridden with SPHINXEXTRA="-j #'.
default is to try use all local CPU cores.

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/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
-                         link.lower().endswith('.jpeg') or
-                         link.lower().endswith('.png') or
-                         link.lower().endswith('.gif')):
-            converted = ".. thumbnail:: " + 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"
+        # 2017-12-07: commented out to disable thumbnail processing due to dropping
+        #             support for obsolete sphinxcontrib.images extension
+        #
+        #if link and (link.lower().endswith('.jpg') or
+        #                 link.lower().endswith('.jpeg') or
+        #                 link.lower().endswith('.png') or
+        #                 link.lower().endswith('.gif')):
+        #    converted = ".. thumbnail:: " + 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%',