diff --git a/src/sage_docbuild/__main__.py b/src/sage_docbuild/__main__.py index 80b4f9270f1..844e1ebee17 100644 --- a/src/sage_docbuild/__main__.py +++ b/src/sage_docbuild/__main__.py @@ -14,47 +14,62 @@ Positional arguments:: - DOCUMENT name of the document to build. It can be either one - of the documents listed by -D or 'file=/path/to/FILE' to build documentation - for this specific file. - FORMAT or COMMAND document output format (or command) + DOCUMENT name of the document to build. It can be either one of + the documents listed by -D or 'file=/path/to/FILE' to + build documentation for this specific file. + FORMAT or COMMAND document output format (or command) Standard options:: - -h, --help show a help message and exit - -H, --help-all show an extended help message and exit - -D, --documents list all available DOCUMENTs - -F, --formats list all output FORMATs - -C DOC, --commands DOC list all COMMANDs for DOCUMENT DOC; use 'all' to list all - -i, --inherited include inherited members in reference manual; may be slow, may fail for PDF output - -u, --underscore include variables prefixed with '_' in reference - manual; may be slow, may fail for PDF output - -j, --mathjax, --jsmath ignored for backwards compatibility - --no-plot do not include graphics auto-generated using the '.. plot' markup - --include-tests-blocks include TESTS blocks in the reference manual - --no-pdf-links do not include PDF links in DOCUMENT 'website'; - FORMATs: html, json, pickle, web - --warn-links issue a warning whenever a link is not properly - resolved; equivalent to '--sphinx-opts -n' (sphinx option: nitpicky) - --check-nested check picklability of nested classes in DOCUMENT 'reference' - --no-prune-empty-dirs do not prune empty directories in the documentation sources - -N, --no-colors do not color output; does not affect children - -q, --quiet work quietly; same as --verbose=0 - -v LEVEL, --verbose LEVEL report progress at LEVEL=0 (quiet), 1 (normal), 2 - (info), or 3 (debug); does not affect children - -o DIR, --output DIR if DOCUMENT is a single file ('file=...'), write output to this directory + -h, --help show a help message and exit + -H, --help-all show an extended help message and exit + -D, --documents list all available DOCUMENTs + -F, --formats list all output FORMATs + -C DOC, --commands DOC + list all COMMANDs for DOCUMENT DOC; use 'all' to list all + -i, --inherited include inherited members in reference manual; may be + slow, may fail for PDF output + -u, --underscore include variables prefixed with '_' in reference + manual; may be slow, may fail for PDF output + -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'; + FORMATs: html, json, pickle, web + --live-doc make Sage code blocks live for html FORMAT + --warn-links issue a warning whenever a link is not properly + resolved; equivalent to '--sphinx-opts -n' (sphinx + option: nitpicky) + --check-nested check picklability of nested classes in DOCUMENT 'reference' + --no-prune-empty-dirs + do not prune empty directories in the documentation sources + --use-cdns assume internet connection and use CDNs; in particular, + use MathJax CDN + -N, --no-colors do not color output; does not affect children + -q, --quiet work quietly; same as --verbose=0 + -v LEVEL, --verbose LEVEL + report progress at LEVEL=0 (quiet), 1 (normal), 2 + (info), or 3 (debug); does not affect children + -o DIR, --output DIR if DOCUMENT is a single file ('file=...'), write output + to this directory Advanced options:: - -S OPTS, --sphinx-opts OPTS pass comma-separated OPTS to sphinx-build; must - precede OPTS with '=', as in '-S=-q,-aE' or '-S="-q,-aE"' - -U, --update-mtimes before building reference manual, update - modification times for auto-generated reST files - -k, --keep-going do not abort on errors but continue as much as - possible after an error - --all-documents ARG if ARG is 'reference', list all subdocuments of - en/reference. If ARG is 'all', list all main documents - + Use these options with care. + + -S OPTS, --sphinx-opts OPTS + pass comma-separated OPTS to sphinx-build; must precede + OPTS with '=', as in '-S=-q,-aE' or '-S="-q,-aE"' + -U, --update-mtimes before building reference manual, update modification + times for auto-generated reST files + -k, --keep-going Do not abort on errors but continue as much as possible + after an error + --all-documents ARG if ARG is 'reference', list all subdocuments of + en/reference. If ARG is 'all', list all main documents """ import logging @@ -69,6 +84,7 @@ logger = logging.getLogger(__name__) + def format_columns(lst, align='<', cols=None, indent=4, pad=3, width=80): """ Utility function that formats a list as a simple table and returns diff --git a/src/sage_docbuild/builders.py b/src/sage_docbuild/builders.py index 475acc5880c..9ffa0480e25 100644 --- a/src/sage_docbuild/builders.py +++ b/src/sage_docbuild/builders.py @@ -867,20 +867,10 @@ def get_sphinx_environment(self): """ Return the Sphinx environment for this project. """ - class FakeConfig(): - values = tuple() - - class FakeApp(): - def __init__(self, dir): - self.srcdir = dir - self.config = FakeConfig() - env_pickle = os.path.join(self._doctrees_dir(), 'environment.pickle') try: with open(env_pickle, 'rb') as f: env = pickle.load(f) - env.app = FakeApp(self.dir) - env.config.values = env.app.config.values logger.debug("Opened Sphinx environment: %s", env_pickle) return env except (OSError, EOFError) as err: @@ -897,29 +887,14 @@ def update_mtimes(self): for doc in env.all_docs: env.all_docs[doc] = time.time() logger.info("Updated %d reST file mtimes", len(env.all_docs)) + # This is the only place we need to save (as opposed to # load) Sphinx's pickle, so we do it right here. - env_pickle = os.path.join(self._doctrees_dir(), - 'environment.pickle') - - # When cloning a new branch (see - # SAGE_LOCAL/bin/sage-clone), we hard link the doc output. - # To avoid making unlinked, potentially inconsistent - # copies of the environment, we *don't* use - # env.topickle(env_pickle), which first writes a temporary - # file. We adapt sphinx.environment's - # BuildEnvironment.topickle: + env_pickle = os.path.join(self._doctrees_dir(), 'environment.pickle') # remove unpicklable attributes env.set_warnfunc(None) - del env.config.values with open(env_pickle, 'wb') as picklefile: - # remove potentially pickling-problematic values from config - for key, val in vars(env.config).items(): - if key.startswith('_') or isinstance(val, (types.ModuleType, - types.FunctionType, - type)): - del env.config[key] pickle.dump(env, picklefile, pickle.HIGHEST_PROTOCOL) logger.debug("Saved Sphinx environment: %s", env_pickle) diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index b07c4ed17e2..4a29787aa46 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -820,7 +820,8 @@ def find_sage_dangling_links(app, env, node, contnode): 'frozenset', 'int', 'list', 'long', 'object', 'set', 'slice', 'str', 'tuple', 'type', 'unicode', 'xrange'] -# Nit picky option configuration: Put here broken links we want to ignore. For + +# nitpicky option configuration: Put here broken links we want to ignore. For # link to the Python documentation several links where broken because there # where class listed as functions. Expand the list 'base_class_as_func' above # instead of marking the link as broken. @@ -828,18 +829,6 @@ def find_sage_dangling_links(app, env, node, contnode): ('py:class', 'twisted.web2.resource.Resource'), ('py:class', 'twisted.web2.resource.PostableResource')] -def nitpick_patch_config(app): - """ - Patch the default config for nitpicky - - Calling path_config ensure that nitpicky is not considered as a Sphinx - environment variable but rather as a Sage environment variable. As a - consequence, changing it doesn't force the recompilation of the entire - documentation. - """ - app.config.values['nitpicky'] = (False, 'sage') - app.config.values['nitpick_ignore'] = ([], 'sage') - skip_picklability_check_modules = [ #'sage.misc.test_nested_class', # for test only @@ -1055,7 +1044,6 @@ def setup(app): # in find_sage_dangling_links. # app.connect('missing-reference', missing_reference) app.connect('missing-reference', find_sage_dangling_links) - app.connect('builder-inited', nitpick_patch_config) app.connect('html-page-context', add_page_context)