more details in docbuild __init__

src/sage_docbuild/__init__.py

@@ -234,9 +234,10 @@ def _output_formats(self):
 
     def pdf(self):
         """
-        Builds the PDF files for this document.  This is done by first
-        (re)-building the LaTeX output, going into that LaTeX
-        directory, and running 'make all-pdf' there.
+        Build the PDF files for this document.
+
+        This is done by first (re)-building the LaTeX output, going
+        into that LaTeX directory, and running 'make all-pdf' there.
 
         EXAMPLES::
 
@@ -366,9 +367,11 @@ def _wrapper(self, name, *args, **kwds):
 
     def get_all_documents(self):
         """
-        Return a list of all of the documents. A document is a directory within one of
-        the language subdirectories of SAGE_DOC_SRC specified by the global LANGUAGES
-        variable.
+        Return a list of all of the documents.
+
+        A document is a directory within one of the language
+        subdirectories of SAGE_DOC_SRC specified by the global
+        LANGUAGES variable.
 
         EXAMPLES::
 
@@ -398,7 +401,7 @@ def get_all_documents(self):
 class WebsiteBuilder(DocBuilder):
     def html(self):
         """
-        After we've finished building the website index page, we copy
+        After we have finished building the website index page, we copy
         everything one directory up.
         """
         DocBuilder.html(self)
@@ -414,9 +417,9 @@ def html(self):
 
     def pdf(self):
         """
-        # Install in the directory one level up to website_dir a symlink to the
-        # directory containing pdf files. This symlink is necessary to access
-        # pdf documentation files within Jupyter (see trac #33206).
+        Install in the directory one level up to website_dir a symlink to the
+        directory containing pdf files. This symlink is necessary to access
+        pdf documentation files within Jupyter (see trac #33206).
         """
         super().pdf()
 
@@ -459,7 +462,7 @@ class ReferenceBuilder(AllBuilder):
     """
     def __init__(self, name, lang='en'):
         """
-        Records the reference manual's name, in case it's not
+        Record the reference manual's name, in case it's not
         identical to 'reference'.
         """
         AllBuilder.__init__(self)
@@ -528,7 +531,7 @@ def _build_top_level(self, format, *args, **kwds):
 
     def _wrapper(self, format, *args, **kwds):
         """
-        Builds reference manuals: build the
+        Build reference manuals: build the
         top-level document and its components.
         """
         logger.info('Building bibliography')
@@ -840,7 +843,7 @@ def __init__(self, dir):
 
     def update_mtimes(self):
         """
-        Updates the modification times for reST files in the Sphinx
+        Update the modification times for reST files in the Sphinx
         environment for this project.
         """
         env = self.get_sphinx_environment()
@@ -900,7 +903,7 @@ def get_modified_modules(self):
 
     def print_modified_modules(self):
         """
-        Prints a list of all the modules that have been modified since
+        Print a list of all the modules that have been modified since
         the documentation was last built.
         """
         for module_name in self.get_modified_modules():
@@ -1052,7 +1055,7 @@ def auto_rest_filename(self, module_name):
 
     def write_auto_rest_file(self, module_name):
         """
-        Writes the autogenerated reST file for module_name.
+        Write the autogenerated reST file for module_name.
         """
         if not module_name.startswith('sage'):
             return
@@ -1130,15 +1133,15 @@ def get_unincluded_modules(self):
 
     def print_unincluded_modules(self):
         """
-        Prints all of the modules which are not included in the Sage
+        Print all of the modules which are not included in the Sage
         reference manual.
         """
         for module_name in self.get_unincluded_modules():
             print(module_name)
 
     def print_included_modules(self):
         """
-        Prints all of the modules that are included in the Sage reference
+        Print all of the modules that are included in the Sage reference
         manual.
         """
         for module_name in self.get_all_included_modules():
@@ -1259,8 +1262,9 @@ def _output_dir(self, type):
 
     def _doctrees_dir(self):
         """
-        Return the directory where the doctrees are stored.  If the
-        directory does not exist, then it will automatically be
+        Return the directory where the doctrees are stored.
+
+        If the directory does not exist, then it will automatically be
         created.
         """
         return self._output_dir('doctrees')
@@ -1269,6 +1273,7 @@ def _doctrees_dir(self):
 def get_builder(name):
     """
     Return an appropriate *Builder object for the document ``name``.
+
     DocBuilder and its subclasses do all the real work in building the
     documentation.
     """
@@ -1326,9 +1331,9 @@ def format_columns(lst, align='<', cols=None, indent=4, pad=3, width=80):
 
 def help_usage(s="", compact=False):
     """
-    Append and return a brief usage message for the Sage
-    documentation builder.  If 'compact' is False, the function adds a
-    final newline character.
+    Append and return a brief usage message for the Sage documentation builder.
+
+    If 'compact' is False, the function adds a final newline character.
     """
     s += "sage --docbuild [OPTIONS] DOCUMENT (FORMAT | COMMAND)"
     if not compact:
@@ -1338,9 +1343,9 @@ def help_usage(s="", compact=False):
 
 def help_description(s="", compact=False):
     """
-    Append and return a brief description of the Sage documentation
-    builder.  If 'compact' is ``False``, the function adds a final newline
-    character.
+    Append and return a brief description of the Sage documentation builder.
+
+    If 'compact' is ``False``, the function adds a final newline character.
     """
     s += "Build or return information about Sage documentation. "
     s += "A DOCUMENT and either a FORMAT or a COMMAND are required."
@@ -1351,8 +1356,7 @@ def help_description(s="", compact=False):
 
 def help_examples(s=""):
     """
-    Append and return some usage examples for the Sage documentation
-    builder.
+    Append and return some usage examples for the Sage documentation builder.
     """
     s += "Examples:\n"
     s += "    sage --docbuild -C all\n"
@@ -1434,7 +1438,7 @@ def help_commands(name='all'):
 
 class help_message_long(argparse.Action):
     """
-    Prints an extended help message for the Sage documentation builder
+    Print an extended help message for the Sage documentation builder
     and exits.
     """
     def __call__(self, parser, namespace, values, option_string=None):
@@ -1449,9 +1453,10 @@ def __call__(self, parser, namespace, values, option_string=None):
 
 class help_message_short(argparse.Action):
     """
-    Prints a help message for the Sage documentation builder.  The
-    message includes command-line usage and a list of options.  The
-    message is printed only on the first call.  If error is True
+    Print a help message for the Sage documentation builder.
+
+    The message includes command-line usage and a list of options.
+    The message is printed only on the first call.  If error is True
     during this call, the message is printed only if the user hasn't
     requested a list (e.g., documents, formats, commands).
     """
@@ -1587,8 +1592,9 @@ def setup_parser():
 
 def setup_logger(verbose=1, color=True):
     r"""
-    Set up a Python Logger instance for the Sage documentation builder. The
-    optional argument sets logger's level and message format.
+    Set up a Python Logger instance for the Sage documentation builder.
+
+    The optional argument sets logger's level and message format.
 
     EXAMPLES::