More edits

src/sage_docbuild/__main__.py

@@ -5,10 +5,10 @@
 
     sage --docbuild [OPTIONS] DOCUMENT (FORMAT | COMMAND)
 
-If ``FORMAT`` is given, ``DOCUMENT`` in given ``FORMAT`` is built. If
-``COMMAND`` is given, it returns information about ``DOCUMENT``.
+If ``FORMAT`` is given, it builds ``DOCUMENT`` in ``FORMAT``. If ``COMMAND`` is
+given, it returns information about ``DOCUMENT``.
 
-To get started, run ``sage --docbuild`` to get detailed explanations about
+Run ``sage --docbuild`` to get detailed explanations about
 arguments and options.
 
 Positional arguments::

src/sage_docbuild/builders.py

@@ -2,36 +2,37 @@
 Documentation builders
 
 This module is the starting point for building documentation, and is
-responsible to figure out what to build and with which options. The
-actual documentation build for each individual document is then done
-in a subprocess call to Sphinx, see :func:`builder_helper`. Note that
+responsible to figure out what to build and with which options. The actual
+documentation build for each individual document is then done in a subprocess
+call to Sphinx, see :func:`builder_helper`. Note that
 
-* The builder can be configured in ``build_options.py``;
+* The builders are configured with ``build_options.py``;
 * The Sphinx subprocesses are configured in ``conf.py``.
 
 :class:`DocBuilder` is the base class of all Builders. It has builder helpers
 :meth:`html()`, :meth:`latex`, :meth:`pdf`, :meth:`inventory`, etc, which are
 invoked depending on the output type. Each type corresponds with the Sphinx
-builder format, except that ``pdf`` is latex Sphinx builder plus compiling
-latex to pdf. Note that ``inventory`` Sphinx builder is not native to Sphinx
+builder format, except that ``pdf`` is Sphinx latex builder plus compiling
+latex to pdf. Note that Sphinx inventory builder is not native to Sphinx
 but provided by Sage. See ``sage_docbuild/ext/inventory_builder.py``. The
-Sphinx inventory builder is the html builder with no actual output but produces
+Sphinx inventory builder is a dummy builder with no actual output but produces
 doctree files in ``local/share/doctree`` and ``inventory.inv`` inventory files
 in ``local/share/inventory``.
 
 The reference manual is built in two passes, first by :class:`ReferenceBuilder`
-with format ``inventory`` and secondly with format ``html``. The
+with ``inventory`` output type and secondly with``html`` output type. The
 :class:`ReferenceBuilder` itself uses :class:`ReferenceTopBuilder` and
 :class:`ReferenceSubBuilder` to build subcomponents of the reference manual.
-The :class:`ReferenceSubBuilder` examines modules of the Sage library by
-comparing the modification times of the module files with the times saved in
-``local/share/doctree/reference.pickle`` from the previous build.  New rst
-files are autogenerated for new and updated modules. See
+The :class:`ReferenceSubBuilder` examines the modules included in the
+subcomponent by comparing the modification times of the module files with the
+times saved in ``local/share/doctree/reference.pickle`` from the previous
+build. Then new rst files are generated for new and updated modules. See
 :meth:`get_new_and_updated_modules()`.
 
 After :trac:`31948`, when Sage is built, :class:`ReferenceBuilder` is not used
 and its responsibility is now taken by the ``Makefile`` in ``$SAGE_ROOT/src/doc``.
 """
+
 # ****************************************************************************
 #       Copyright (C) 2008-2009 Mike Hansen <mhansen@gmail.com>
 #                     2009-2010 Mitesh Patel <qed777@gmail.com>
@@ -59,6 +60,7 @@
 # (at your option) any later version.
 #                  https://www.gnu.org/licenses/
 # ****************************************************************************
+
 import logging
 import os
 import pickle