src/sage_setup/autogen/interpreters/__init__.py: Add doc and test

src/sage_setup/autogen/interpreters/__init__.py

@@ -165,7 +165,23 @@ def rebuild(dirname, force=False, interpreters=None, distribution=None):
     Check whether the interpreter and wrapper sources have been written
     since the last time this module was changed.  If not, write them.
 
-    EXAMPLES::
+    INPUT:
+
+    - ``dirname`` -- name of the target directory for the generated sources
+
+    - ``force`` -- boolean (default ``False``); if ``True``, ignore timestamps
+      and regenerate the sources unconditionally
+
+    - ``interpreters`` -- an iterable of strings, or ``None`` (the default,
+      which means all interpreters); which interpreters to generate
+
+    - ``distribution`` -- a string (the distribution name such as
+      ``"sagemath-categories"``)  or ``None`` (the default, which means
+      the monolithic Sage library)
+
+    EXAMPLES:
+
+    Monolithic build::
 
         sage: from sage_setup.autogen.interpreters import *
         sage: testdir = tmp_dir()
@@ -175,6 +191,17 @@ def rebuild(dirname, force=False, interpreters=None, distribution=None):
         sage: with open(testdir + '/wrapper_el.pyx') as f:
         ....:     f.readline()
         '# Automatically generated by ...\n'
+
+    Modularized build::
+
+        sage: testdir = tmp_dir()
+        sage: rebuild(testdir, interpreters=['Element', 'Python'],
+        ....:         distribution='sagemath-categories')
+        Building interpreters for fast_callable
+        -> First build of interpreters
+        sage: with open(testdir + '/all__sagemath_categories.py') as f:
+        ....:     f.readline()
+        '# Automatically generated by ...\n'
     """
     # This line will show up in "sage -b" (once per upgrade, not every time
     # you run it).