Comment on fork logic in docbuilding

src/sage_setup/docbuild/__init__.py

@@ -265,6 +265,14 @@ def clean(self, *args):
     inventory = builder_helper('inventory')
 
 def build_many(target, args):
+    # Pool() uses an actual fork() to run each new instance. This is important
+    # for performance reasons, i.e., don't use a forkserver when it becomes
+    # available with Python 3: Here, sage is already initialized which is quite
+    # costly, with a forkserver we would have to reinitialize it for every
+    # document we build. At the same time, don't serialize this by taking the
+    # pool (and thus the call to fork()) out completely: The call to Sphinx
+    # leaks memory, so we need to build each document in its own process to
+    # control the RAM usage.
     from multiprocessing import Pool
     pool = Pool(NUM_THREADS, maxtasksperchild=1)
     # map_async handles KeyboardInterrupt correctly. Plain map and

src/sage_setup/docbuild/sphinxbuild.py

@@ -309,6 +309,11 @@ def runsphinx():
     try:
         sys.stdout = SageSphinxLogger(sys.stdout, os.path.basename(output_dir))
         sys.stderr = SageSphinxLogger(sys.stderr, os.path.basename(output_dir))
+        # Note that this call as of eraly 2018 leaks memory. So make sure that
+        # you don't call runsphinx() several times in a row. (i.e., you want to
+        # fork() somewhere before this call.)
+        # We don't use subprocess here, as we don't want to re-initialize Sage
+        # for every docbuild as this takes a while.
         sphinx.cmdline.main(sys.argv)
         sys.stderr.raise_errors()
         sys.stdout.raise_errors()