Minor documentation formatting improvement

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

@@ -77,7 +77,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)
@@ -335,7 +337,7 @@ 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::
 
-        sage --docbuild --warn-links reference html
+    sage --docbuild --warn-links reference html
 
 .. _section-manuals-names:
 

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
@@ -174,10 +179,10 @@
 
         EXAMPLES::
 
             sage: from sage_docbuild.builders import DocBuilder
             sage: from sage_docbuild.build_options import BuildOptions
             sage: import tempfile
             sage: with tempfile.TemporaryDirectory() as directory:
             ....:   options = BuildOptions(output_dir=Path(directory), source_dir=Path('src/doc'))
             ....:   builder = DocBuilder('en/tutorial', options)
             ....:   builder._output_dir('html')
@@ -196,10 +201,10 @@
 
         EXAMPLES::
 
             sage: from sage_docbuild.builders import DocBuilder
             sage: from sage_docbuild.build_options import BuildOptions
             sage: import tempfile
             sage: with tempfile.TemporaryDirectory() as directory:
             ....:   options = BuildOptions(output_dir=Path(directory), source_dir=Path('src/doc'))
             ....:   builder = DocBuilder('en/tutorial', options)
             ....:   builder._doctrees_dir()
@@ -215,10 +220,10 @@
 
         EXAMPLES::
 
             sage: from sage_docbuild.builders import DocBuilder
             sage: from sage_docbuild.build_options import BuildOptions
             sage: options = BuildOptions(source_dir=Path('src/doc'))
             sage: builder = DocBuilder('tutorial', options)
             sage: builder._output_formats()
             ['changes', 'html', 'htmlhelp', 'inventory', 'json', 'latex', 'linkcheck', 'pickle', 'web']
         """
@@ -293,7 +298,7 @@
 
 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: