From 1040829d8d50007153202da959f5f304b7f377f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Chapoton?= Date: Sun, 6 Feb 2022 16:13:50 +0100 Subject: [PATCH] more details in docbuild __init__ --- src/sage_docbuild/__init__.py | 72 +++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 33 deletions(-) diff --git a/src/sage_docbuild/__init__.py b/src/sage_docbuild/__init__.py index 316f652f43e..0c04c37d75a 100644 --- a/src/sage_docbuild/__init__.py +++ b/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,7 +1133,7 @@ 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(): @@ -1138,7 +1141,7 @@ def print_unincluded_modules(self): 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::