passagemath-docbuild 10.8.1a3__tar.gz → 10.8.1rc0__tar.gz

{passagemath_docbuild-10.8.1a3/passagemath_docbuild.egg-info → passagemath_docbuild-10.8.1rc0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: passagemath-docbuild
-Version: 10.8.1a3
+Version: 10.8.1rc0
 Summary: passagemath: Build system of the Sage documentation
 Author-email: The Sage Developers <sage-support@googlegroups.com>
 Maintainer: Matthias Köppe, passagemath contributors

passagemath_docbuild-10.8.1rc0/VERSION.txt

@@ -0,0 +1 @@
+10.8.1.rc0

{passagemath_docbuild-10.8.1a3 → passagemath_docbuild-10.8.1rc0/passagemath_docbuild.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: passagemath-docbuild
-Version: 10.8.1a3
+Version: 10.8.1rc0
 Summary: passagemath: Build system of the Sage documentation
 Author-email: The Sage Developers <sage-support@googlegroups.com>
 Maintainer: Matthias Köppe, passagemath contributors

{passagemath_docbuild-10.8.1a3 → passagemath_docbuild-10.8.1rc0}/sage_docbuild/__main__.py

@@ -34,6 +34,8 @@ Standard options::
   -j, --mathjax, --jsmath
                         ignored for backwards compatibility
   --no-plot             do not include graphics auto-generated using the '.. plot' markup
+  --no-preparsed-examples
+                        do not show preparsed versions of EXAMPLES blocks
   --include-tests-blocks
                         include TESTS blocks in the reference manual
   --no-pdf-links        do not include PDF links in DOCUMENT 'website';
@@ -70,22 +72,15 @@ Advanced options::
                         en/reference. If ARG is 'all', list all main documents
 """
 
-import argparse
 import logging
+import argparse
 import os
+import shlex
 import sys
-from pathlib import Path
-
 import sphinx.ext.intersphinx
-
+from sage.env import SAGE_DOC_SRC
+from .builders import DocBuilder, ReferenceBuilder, get_builder, get_documents
 from . import build_options
-from .build_options import BuildOptions
-from .builders import (
-    DocBuilder,
-    get_all_documents,
-    get_all_reference_documents,
-    get_builder,
-)
 
 logger = logging.getLogger(__name__)
 
@@ -166,7 +161,7 @@ def help_documents():
     s += "\n"
     if 'reference' in docs:
         s += "Other valid document names take the form 'reference/DIR', where\n"
-        s += "DIR is a subdirectory of src/doc/en/reference/.\n"
+        s += "DIR is a subdirectory of SAGE_DOC_SRC/en/reference/.\n"
         s += "This builds just the specified part of the reference manual.\n"
     s += "DOCUMENT may also have the form 'file=/path/to/FILE', which builds\n"
     s += "the documentation for the specified file.\n"
@@ -178,7 +173,7 @@ def get_formats():
     Return a list of output formats the Sage documentation builder
     will accept on the command-line.
     """
-    tut_b = DocBuilder('en/tutorial', BuildOptions())
+    tut_b = DocBuilder('en/tutorial')
     formats = tut_b._output_formats()
     formats.remove('html')
     return ['html', 'pdf'] + formats
@@ -256,6 +251,21 @@ class help_wrapper(argparse.Action):
             print(help_formats(), end="")
         if self.dest == 'commands':
             print(help_commands(values), end="")
+        if self.dest == 'all_documents':
+            if values == 'reference':
+                b = ReferenceBuilder('reference')
+                refdir = os.path.join(os.environ['SAGE_DOC_SRC'], 'en', b.name)
+                s = b.get_all_documents(refdir)
+                # Put the bibliography first, because it needs to be built first:
+                s.remove('reference/references')
+                s.insert(0, 'reference/references')
+            elif values == 'all':
+                s = get_documents()
+                # Put the reference manual first, because it needs to be built first:
+                s.remove('reference')
+                s.insert(0, 'reference')
+            for d in s:
+                print(d)
         setattr(namespace, 'printed_list', 1)
         sys.exit(0)
 
@@ -295,6 +305,9 @@ def setup_parser():
     standard.add_argument("--no-plot", dest="no_plot",
                           action="store_true",
                           help="do not include graphics auto-generated using the '.. plot' markup")
+    standard.add_argument("--no-preparsed-examples", dest="no_preparsed_examples",
+                          action="store_true",
+                          help="do not show preparsed versions of EXAMPLES blocks")
     standard.add_argument("--include-tests-blocks", dest="skip_tests", default=True,
                           action="store_false",
                           help="include TESTS blocks in the reference manual")
@@ -326,11 +339,7 @@ def setup_parser():
                           type=int, default=1, metavar="LEVEL",
                           action="store",
                           help="report progress at LEVEL=0 (quiet), 1 (normal), 2 (info), or 3 (debug); does not affect children")
-    standard.add_argument("-s", "--source", dest="source_dir", type=Path,
-                          default=None, metavar="DIR", action="store",
-                          help="directory containing the documentation source files")
     standard.add_argument("-o", "--output", dest="output_dir", default=None,
-                            type=Path,
                           metavar="DIR", action="store",
                           help="if DOCUMENT is a single file ('file=...'), write output to this directory")
 
@@ -350,6 +359,7 @@ def setup_parser():
     advanced.add_argument("--all-documents", dest="all_documents",
                           type=str, metavar="ARG",
                           choices=['all', 'reference'],
+                          action=help_wrapper,
                           help="if ARG is 'reference', list all subdocuments"
                           " of en/reference. If ARG is 'all', list all main"
                           " documents")
@@ -446,35 +456,8 @@ class IntersphinxCache:
 def main():
     # Parse the command-line.
     parser = setup_parser()
-    args: BuildOptions = parser.parse_args() # type: ignore
-
-    # Check that the docs source directory exists
-    if args.source_dir is None:
-        args.source_dir = Path(os.environ.get('SAGE_DOC_SRC', 'src/doc'))
-    args.source_dir = args.source_dir.absolute()
-    if not args.source_dir.is_dir():
-        parser.error(f"Source directory {args.source_dir} does not exist.")
-    
-    if args.all_documents:
-        if args.all_documents == 'reference':
-            docs = get_all_reference_documents(args.source_dir / 'en')
-        elif args.all_documents == 'all':
-            docs = get_all_documents(args.source_dir)
-        else:
-            parser.error(f"Unknown argument {args.all_documents} for --all-documents.")
-        for d in docs:
-            print(d.as_posix())
-        sys.exit(0)
-
-    # Check that the docs output directory exists
-    if args.output_dir is None:
-        args.output_dir = Path(os.environ.get('SAGE_DOC', 'src/doc'))    
-    args.output_dir = args.output_dir.absolute()
-    if not args.output_dir.exists():
-        try:
-            args.output_dir.mkdir(parents=True)
-        except Exception as e:
-            parser.error(f"Failed to create output directory {args.output_dir}: {e}")
+    args = parser.parse_args()
+    DocBuilder._options = args
 
     # Get the name and type (target format) of the document we are
     # trying to build.
@@ -482,24 +465,30 @@ def main():
     if not name or not typ:
         parser.print_help()
         sys.exit(1)
+    elif name == 'all':
+        sys.exit(os.system(f'cd {shlex.quote(SAGE_DOC_SRC)} '
+                           f'&& ${{MAKE:-make}} -j${{SAGE_NUM_THREADS_PARALLEL:-1}} doc-{typ}'))
 
     # Set up module-wide logging.
     setup_logger(args.verbose, args.color)
 
     def excepthook(*exc_info):
         logger.error('Error building the documentation.', exc_info=exc_info)
-        logger.info('''
-Note: incremental documentation builds sometimes cause spurious
-error messages. To be certain that these are real errors, run
-"make doc-clean doc-uninstall" first and try again.''')
+        if build_options.INCREMENTAL_BUILD:
+            logger.error('''
+    Note: incremental documentation builds sometimes cause spurious
+    error messages. To be certain that these are real errors, run
+    "make doc-clean doc-uninstall" first and try again.''')
 
     sys.excepthook = excepthook
 
-    # Set up the environment based on the command-line options
+    # Process selected options.
     if args.check_nested:
         os.environ['SAGE_CHECK_NESTED'] = 'True'
+
     if args.underscore:
         os.environ['SAGE_DOC_UNDERSCORE'] = "True"
+
     if args.sphinx_opts:
         build_options.ALLSPHINXOPTS += args.sphinx_opts.replace(',', ' ') + " "
     if args.no_pdf_links:
@@ -508,21 +497,21 @@ error messages. To be certain that these are real errors, run
         build_options.ALLSPHINXOPTS += "-n "
     if args.no_plot:
         os.environ['SAGE_SKIP_PLOT_DIRECTIVE'] = 'yes'
+    if args.no_preparsed_examples:
+        os.environ['SAGE_PREPARSED_DOC'] = 'no'
     if args.live_doc:
         os.environ['SAGE_LIVE_DOC'] = 'yes'
     if args.skip_tests:
         os.environ['SAGE_SKIP_TESTS_BLOCKS'] = 'True'
     if args.use_cdns:
         os.environ['SAGE_USE_CDNS'] = 'yes'
-    os.environ['SAGE_DOC_SRC'] = str(args.source_dir)
-    os.environ['SAGE_DOC'] = str(args.output_dir)
 
     build_options.ABORT_ON_ERROR = not args.keep_going
 
     # Set up Intersphinx cache
     _ = IntersphinxCache()
 
-    builder = get_builder(name, args)
+    builder = get_builder(name)
 
     if not args.no_prune_empty_dirs:
         # Delete empty directories. This is needed in particular for empty
@@ -530,13 +519,11 @@ error messages. To be certain that these are real errors, run
         # directories it leaves behind. See Issue #20010.
         # Issue #31948: This is not parallelization-safe; use the option
         # --no-prune-empty-dirs to turn it off
-        for dirpath, dirnames, filenames in os.walk(args.source_dir, topdown=False):
+        for dirpath, dirnames, filenames in os.walk(builder.dir, topdown=False):
             if not dirnames + filenames:
                 logger.warning('Deleting empty directory {0}'.format(dirpath))
                 os.rmdir(dirpath)
 
-    import sage.all  # TODO: Remove once all modules can be imported independently  # noqa: F401
-
     build = getattr(builder, typ)
     build()
 

{passagemath_docbuild-10.8.1a3 → passagemath_docbuild-10.8.1rc0}/sage_docbuild/build_options.py

@@ -4,10 +4,12 @@ Build options
 This module defines options for building Sage documentation.
 """
 
-import argparse
 import os
-from pathlib import Path
+import re
 
+from sage.env import SAGE_DOC_SRC, SAGE_DOC
+
+LANGUAGES = [d for d in os.listdir(SAGE_DOC_SRC) if re.match('^[a-z][a-z]$', d)]
 SPHINXOPTS = ""
 PAPER = ""
 OMIT = ["introspect"]  # docs/dirs to omit when listing and building 'all'
@@ -24,9 +26,7 @@ WEBSITESPHINXOPTS = ""
 # Number of threads to use for parallel-building the documentation.
 NUM_THREADS = int(os.environ.get('SAGE_NUM_THREADS', 1))
 
+INCREMENTAL_BUILD = os.path.isdir(SAGE_DOC)
+
 # Error out on errors
 ABORT_ON_ERROR = True
-
-class BuildOptions(argparse.Namespace):
-    source_dir: Path
-    output_dir: Path