Minor documentation formatting improvement

Author: user202729

pkgs/sage-docbuild/README.rst

@@ -2,6 +2,11 @@
  Sage: Open Source Mathematics Software: Build system of the Sage documentation
 ================================================================================
 
+.. NOTE::
+
+   If you are a developer and want to build the SageMath documentation from source,
+   refer to `developer's guide <../../developer/sage_manuals.html>`.
+
 About SageMath
 --------------
 

src/doc/en/developer/sage_manuals.rst

@@ -47,7 +47,9 @@ Editing the documentation
 
 After modifying some files in the Sage tutorial
 (:sage_root:`src/doc/en/tutorial/`), you will want to visualize the result. In
-order to build a **html** version of this document, type::
+order to build a **html** version of this document, type:
+
+.. CODE-BLOCK:: bash
 
     sage --docbuild tutorial html
 
@@ -62,13 +64,17 @@ your web browser.
 
 **Run doctests:** All files must pass tests. After modifying a document
 (e.g. ``tutorial``), you can run tests with the following command (see
-:ref:`chapter-testing`)::
+:ref:`chapter-testing`):
+
+.. CODE-BLOCK:: bash
 
     sage -tp SAGE_ROOT/src/doc/en/tutorial/
 
 **Reference manual:** as this manual is mostly generated from Sage's source
 code, you will need to build Sage in order to see the changes you made to some
-function's documentation.  Type::
+function's documentation.  Type:
+
+.. CODE-BLOCK:: bash
 
     sage -b && sage --docbuild reference html
 
@@ -77,7 +83,9 @@ function's documentation.  Type::
 Hyperlinks
 ==========
 
-The documentation can contain links toward modules, classes, or methods, e.g.::
+The documentation can contain links toward modules, classes, or methods, e.g.:
+
+.. CODE-BLOCK:: rest
 
     :mod:`link to a module <sage.module_name>`
     :mod:`sage.module_name` (here the link's text is the module's name)
@@ -313,16 +321,22 @@ script.  The content of the ``sage --docbuild`` script is defined in
 the ``sphinx-build`` script which does all of the real work.  It is
 designed to be a replacement for the default Makefiles generated by
 the ``sphinx-quickstart`` script.  The general form of the command
-is::
+is:
+
+.. CODE-BLOCK:: bash
 
     sage --docbuild <document-name> <format>
 
-For example::
+For example:
+
+.. CODE-BLOCK:: bash
 
     sage --docbuild reference html
 
 Two **help** commands which give plenty of documentation for the ``sage
---docbuild`` script::
+--docbuild`` script:
+
+.. CODE-BLOCK:: bash
 
     sage --docbuild -h # short help message
     sage --docbuild -H # a more comprehensive one
@@ -333,9 +347,11 @@ used in Sage. See `<http://www.sphinx-doc.org/builders.html>`_.
 **Broken links:** in order to build the documentation while reporting the broken
 links that it contains, use the ``--warn-links`` flag. Note that Sphinx will not
 rebuild a document that has not been updated, and thus not report its broken
-links::
+links:
+
+.. CODE-BLOCK:: bash
 
-        sage --docbuild --warn-links reference html
+    sage --docbuild --warn-links reference html
 
 .. _section-manuals-names:
 
@@ -351,12 +367,16 @@ The ``<document-name>`` has the form:
 where ``lang`` is a two-letter language code, and ``name`` is the
 descriptive name of the document.  If the language is not specified,
 then it defaults to English (``en``).  The following two commands do
-the exact same thing::
+the exact same thing:
+
+.. CODE-BLOCK:: bash
 
     sage --docbuild tutorial html
     sage --docbuild en/tutorial html
 
-To specify the French version of the tutorial, you would simply run::
+To specify the French version of the tutorial, you would simply run:
+
+.. CODE-BLOCK:: bash
 
     sage --docbuild fr/tutorial html
 

src/sage_docbuild/builders.py

@@ -2,6 +2,11 @@
 """
 Documentation builders
 
+.. NOTE::
+
+   If you are a developer and want to build the SageMath documentation from source,
+   refer to `developer's guide <../../../developer/sage_manuals.html>`.
+
 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
@@ -21,7 +26,7 @@
 in ``local/share/inventory``.
 
 The reference manual is built in two passes, first by :class:`ReferenceBuilder`
-with ``inventory`` output type and secondly with``html`` output type. 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 the modules included in the
@@ -293,7 +298,7 @@ def clean(self, *args):
 
 def build_many(target, args, processes=None):
     """
-    Thin wrapper around `sage_docbuild.utils.build_many` which uses the
+    Thin wrapper around :func:`sage_docbuild.utils.build_many` which uses the
     docbuild settings ``NUM_THREADS`` and ``ABORT_ON_ERROR``.
     """
     if processes is None: