From 2571572fd6eeb509808e16e70682dde2e1218d04 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Fri, 14 Dec 2018 03:34:51 +0000 Subject: [PATCH 1/9] WIP: Major refactoring and clean up, still some problems on building the api pages --- doc/make.py | 257 ++++++++++------------------------ doc/source/conf.py | 52 ++++++- doc/source/index.rst.template | 4 +- 3 files changed, 125 insertions(+), 188 deletions(-) diff --git a/doc/make.py b/doc/make.py index 0a3a7483fcc91..b7ed726f6c62b 100755 --- a/doc/make.py +++ b/doc/make.py @@ -19,7 +19,6 @@ import argparse from contextlib import contextmanager import webbrowser -import jinja2 DOC_PATH = os.path.dirname(os.path.abspath(__file__)) @@ -28,179 +27,67 @@ BUILD_DIRS = ['doctrees', 'html', 'latex', 'plots', '_static', '_templates'] -@contextmanager -def _maybe_exclude_notebooks(): - """Skip building the notebooks if pandoc is not installed. - - This assumes that nbsphinx is installed. - - Skip notebook conversion if: - 1. nbconvert isn't installed, or - 2. nbconvert is installed, but pandoc isn't - """ - # TODO move to exclude_pattern - base = os.path.dirname(__file__) - notebooks = [os.path.join(base, 'source', nb) - for nb in ['style.ipynb']] - contents = {} - - def _remove_notebooks(): - for nb in notebooks: - with open(nb, 'rt') as f: - contents[nb] = f.read() - os.remove(nb) - - try: - import nbconvert - except ImportError: - sys.stderr.write('Warning: nbconvert not installed. ' - 'Skipping notebooks.\n') - _remove_notebooks() - else: - try: - nbconvert.utils.pandoc.get_pandoc_version() - except nbconvert.utils.pandoc.PandocMissing: - sys.stderr.write('Warning: Pandoc is not installed. ' - 'Skipping notebooks.\n') - _remove_notebooks() - - yield - - for nb, content in contents.items(): - with open(nb, 'wt') as f: - f.write(content) - - class DocBuilder: - """Class to wrap the different commands of this script. + """ + Class to wrap the different commands of this script. All public methods of this class can be called as parameters of the script. """ def __init__(self, num_jobs=1, include_api=True, single_doc=None, - verbosity=0): + verbosity=0, warnings_are_errors=False): self.num_jobs = num_jobs - self.include_api = include_api self.verbosity = verbosity - self.single_doc = None - self.single_doc_type = None - if single_doc is not None: - self._process_single_doc(single_doc) - self.exclude_patterns = self._exclude_patterns - - self._generate_index() - if self.single_doc_type == 'docstring': - self._run_os('sphinx-autogen', '-o', - 'source/generated_single', 'source/index.rst') - - @property - def _exclude_patterns(self): - """Docs source files that will be excluded from building.""" - # TODO move maybe_exclude_notebooks here - if self.single_doc is not None: - rst_files = [f for f in os.listdir(SOURCE_PATH) - if ((f.endswith('.rst') or f.endswith('.ipynb')) - and (f != 'index.rst') - and (f != '{0}.rst'.format(self.single_doc)))] - if self.single_doc_type != 'api': - rst_files += ['generated/*.rst'] - elif not self.include_api: - rst_files = ['api.rst', 'generated/*.rst'] - else: - rst_files = ['generated_single/*.rst'] + self.warnings_are_errors = warnings_are_errors - exclude_patterns = ','.join( - '{!r}'.format(i) for i in ['**.ipynb_checkpoints'] + rst_files) + if single_doc: + single_doc = self._process_single_doc(single_doc) + include_api = False + os.environ['SPHINX_PATTERN'] = single_doc + elif not include_api: + os.environ['SPHINX_PATTERN'] = '-api' - return exclude_patterns + # if self.single_doc_type == 'docstring': + # self._run_os('sphinx-autogen', os.path.join(SOURCE_PATH, 'index.rst')) - def _process_single_doc(self, single_doc): - """Extract self.single_doc (base name) and self.single_doc_type from - passed single_doc kwarg. + if single_doc: + self.single_doc_html = os.path.splitext(single_doc)[0] + '.html' - """ - self.include_api = False - if single_doc == 'api.rst' or single_doc == 'api': - self.single_doc_type = 'api' - self.single_doc = 'api' - elif os.path.exists(os.path.join(SOURCE_PATH, single_doc)): - self.single_doc_type = 'rst' + def _process_single_doc(self, single_doc): + """ + Make sure the provided value for --single is a path to an existing + .rst/.ipynb file, or a pandas object that can be imported. - if 'whatsnew' in single_doc: - basename = single_doc + For example, categorial.rst or pandas.DataFrame.head. For the latter, + return the corresponding file path + (e.g. generated/pandas.DataFrame.head.rst). + """ + base_name, extension = os.path.splitext(single_doc) + if extension in ('.rst', '.ipynb'): + if os.path.exists(os.path.join(SOURCE_PATH, single_doc)): + return single_doc else: - basename = os.path.basename(single_doc) - self.single_doc = os.path.splitext(basename)[0] - elif os.path.exists( - os.path.join(SOURCE_PATH, '{}.rst'.format(single_doc))): - self.single_doc_type = 'rst' - self.single_doc = single_doc - elif single_doc is not None: + raise FileNotFoundError('File {} not found'.format(single_doc)) + + elif single_doc.startswith('pandas.'): try: obj = pandas # noqa: F821 for name in single_doc.split('.'): obj = getattr(obj, name) except AttributeError: - raise ValueError('Single document not understood, it should ' - 'be a file in doc/source/*.rst (e.g. ' - '"contributing.rst" or a pandas function or ' - 'method (e.g. "pandas.DataFrame.head")') + raise ImportError('Could not import {}'.format(single_doc)) else: - self.single_doc_type = 'docstring' - if single_doc.startswith('pandas.'): - self.single_doc = single_doc[len('pandas.'):] - else: - self.single_doc = single_doc - - def _copy_generated_docstring(self): - """Copy existing generated (from api.rst) docstring page because - this is more correct in certain cases (where a custom autodoc - template is used). - - """ - fname = os.path.join(SOURCE_PATH, 'generated', - 'pandas.{}.rst'.format(self.single_doc)) - temp_dir = os.path.join(SOURCE_PATH, 'generated_single') - - try: - os.makedirs(temp_dir) - except OSError: - pass - - if os.path.exists(fname): - try: - # copying to make sure sphinx always thinks it is new - # and needs to be re-generated (to pick source code changes) - shutil.copy(fname, temp_dir) - except: # noqa - pass - - def _generate_index(self): - """Create index.rst file with the specified sections.""" - if self.single_doc_type == 'docstring': - self._copy_generated_docstring() - - with open(os.path.join(SOURCE_PATH, 'index.rst.template')) as f: - t = jinja2.Template(f.read()) - - with open(os.path.join(SOURCE_PATH, 'index.rst'), 'w') as f: - f.write(t.render(include_api=self.include_api, - single_doc=self.single_doc, - single_doc_type=self.single_doc_type)) - - @staticmethod - def _create_build_structure(): - """Create directories required to build documentation.""" - for dirname in BUILD_DIRS: - try: - os.makedirs(os.path.join(BUILD_PATH, dirname)) - except OSError: - pass + return os.path.join('generated', '{}.rst'.format(single_doc)) + else: + raise ValueError('--single value should be a valid path to a ' + '.rst or .ipynb file, or a valid pandas object ' + '(e.g. categorical.rst or pandas.DataFrame.head)') @staticmethod def _run_os(*args): - """Execute a command as a OS terminal. + """ + Execute a command as a OS terminal. Parameters ---------- @@ -211,13 +98,12 @@ def _run_os(*args): -------- >>> DocBuilder()._run_os('python', '--version') """ - # TODO check_call should be more safe, but it fails with - # exclude patterns, needs investigation - # subprocess.check_call(args, stderr=subprocess.STDOUT) os.system(' '.join(args)) + #subprocess.check_call(args, stderr=subprocess.STDOUT) def _sphinx_build(self, kind): - """Call sphinx to build documentation. + """ + Call sphinx to build documentation. Attribute `num_jobs` from the class is used. @@ -236,40 +122,36 @@ def _sphinx_build(self, kind): self._run_os('sphinx-build', '-j{}'.format(self.num_jobs), '-b{}'.format(kind), + '-W' if self.warnings_are_errors else '', '-{}'.format( 'v' * self.verbosity) if self.verbosity else '', '-d"{}"'.format(os.path.join(BUILD_PATH, 'doctrees')), - '-Dexclude_patterns={}'.format(self.exclude_patterns), '"{}"'.format(SOURCE_PATH), '"{}"'.format(os.path.join(BUILD_PATH, kind))) - def _open_browser(self): - base_url = os.path.join('file://', DOC_PATH, 'build', 'html') - if self.single_doc_type == 'docstring': - url = os.path.join( - base_url, - 'generated_single', 'pandas.{}.html'.format(self.single_doc)) - else: - url = os.path.join(base_url, '{}.html'.format(self.single_doc)) + def _open_browser(self, single_doc_html): + """ + Open a browser tab showing single + """ + url = os.path.join('file://', DOC_PATH, 'build', 'html', single_doc_html) webbrowser.open(url, new=2) def html(self): - """Build HTML documentation.""" - self._create_build_structure() - with _maybe_exclude_notebooks(): - self._sphinx_build('html') - zip_fname = os.path.join(BUILD_PATH, 'html', 'pandas.zip') - if os.path.exists(zip_fname): - os.remove(zip_fname) - - if self.single_doc is not None: - self._open_browser() - shutil.rmtree(os.path.join(SOURCE_PATH, 'generated_single'), - ignore_errors=True) + """ + Build HTML documentation. + """ + self._sphinx_build('html') + zip_fname = os.path.join(BUILD_PATH, 'html', 'pandas.zip') + if os.path.exists(zip_fname): + os.remove(zip_fname) + + if self.single_doc_html is not None: + self._open_browser(self.single_doc_html) def latex(self, force=False): - """Build PDF documentation.""" - self._create_build_structure() + """ + Build PDF documentation. + """ if sys.platform == 'win32': sys.stderr.write('latex build has not been tested on windows\n') else: @@ -286,18 +168,24 @@ def latex(self, force=False): self._run_os('make') def latex_forced(self): - """Build PDF documentation with retries to find missing references.""" + """ + Build PDF documentation with retries to find missing references. + """ self.latex(force=True) @staticmethod def clean(): - """Clean documentation generated files.""" + """ + Clean documentation generated files. + """ shutil.rmtree(BUILD_PATH, ignore_errors=True) shutil.rmtree(os.path.join(SOURCE_PATH, 'generated'), ignore_errors=True) def zip_html(self): - """Compress HTML documentation into a zip file.""" + """ + Compress HTML documentation into a zip file. + """ zip_fname = os.path.join(BUILD_PATH, 'html', 'pandas.zip') if os.path.exists(zip_fname): os.remove(zip_fname) @@ -311,7 +199,9 @@ def zip_html(self): *fnames) def spellcheck(self): - """Spell check the documentation.""" + """ + Spell check the documentation. + """ self._sphinx_build('spelling') output_location = os.path.join('build', 'spelling', 'output.txt') with open(output_location) as output: @@ -354,6 +244,9 @@ def main(): argparser.add_argument('-v', action='count', dest='verbosity', default=0, help=('increase verbosity (can be repeated), ' 'passed to the sphinx build command')) + argparser.add_argument('--warnings-are-errors', '-W', + action='store_true', + help='fail if warnings are raised') args = argparser.parse_args() if args.command not in cmds: @@ -373,7 +266,7 @@ def main(): os.environ['MPLBACKEND'] = 'module://matplotlib.backends.backend_agg' builder = DocBuilder(args.num_jobs, not args.no_api, args.single, - args.verbosity) + args.verbosity, args.warnings_are_errors) getattr(builder, args.command)() diff --git a/doc/source/conf.py b/doc/source/conf.py index 56f77f667df88..2174a797f0f2e 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -18,6 +18,7 @@ import importlib import logging import warnings +import jinja2 from sphinx.ext.autosummary import _import_by_name logger = logging.getLogger(__name__) @@ -86,6 +87,48 @@ extensions.append('sphinxcontrib.spelling') exclude_patterns = ['**.ipynb_checkpoints'] +try: + import nbconvert +except ImportError: + logger.warn('nbconvert not installed. Skipping notebooks.') + exclude_patterns.append('**/*.ipynb') +else: + try: + nbconvert.utils.pandoc.get_pandoc_version() + except nbconvert.utils.pandoc.PandocMissing: + logger.warn('Pandoc not installed. Skipping notebooks.') + exclude_patterns.append('**/*.ipynb') + +# sphinx_pattern can be '-api' to exclude the API pages, +# or the path to a file (e.g. '10min.rst' or 'generated/pandas.DataFrame.head.rst') +source_path = os.path.dirname(os.path.abspath(__file__)) +pattern = os.environ.get('SPHINX_PATTERN') +if pattern: + for dirname, dirs, fnames in os.walk(source_path): + for fname in fnames: + if os.path.splitext(fname)[-1] in ('.rst', '.ipynb'): + fname = os.path.relpath(os.path.join(dirname, fname), source_path) + + if (fname == 'index.rst' + and os.path.abspath(dirname) == source_path): + continue + elif (pattern == '-api' + and (fname == 'api.rst' or dirname == 'generated')): + exclude_patterns.append(fname) + elif fname != pattern: + exclude_patterns.append(fname) + +print(exclude_patterns) + +with open(os.path.join(source_path, 'index.rst.template')) as f: + t = jinja2.Template(f.read()) + +with open(os.path.join(source_path, 'index.rst'), 'w') as f: + f.write(t.render(include_api=pattern is None, + single_doc=os.path.splitext(pattern)[0] + if pattern is not None and pattern != '-api' + else None)) + spelling_word_list_filename = ['spelling_wordlist.txt', 'names_wordlist.txt'] spelling_ignore_pypi_package_names = True @@ -295,10 +338,11 @@ "{new}.{method}".format(new=new, method=method)) ) -html_additional_pages = { - 'generated/' + page[0]: 'api_redirect.html' - for page in moved_api_pages -} +if pattern is None: + html_additional_pages = { + 'generated/' + page[0]: 'api_redirect.html' + for page in moved_api_pages + } header = """\ diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index 38f73f8617ced..7b2811f2146c5 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -106,9 +106,9 @@ Some other notes See the package overview for more detail about what's in the library. -{% if single_doc_type == 'docstring' -%} +{% if single_doc and single_doc.startswith('generated') -%} .. autosummary:: - :toctree: generated_single/ + :toctree: generated/ {% else -%} .. toctree:: :maxdepth: 4 From 83c3b45be6c6914729d2860339f0fc4b97a41a1e Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Fri, 14 Dec 2018 18:56:59 +0000 Subject: [PATCH 2/9] building only api pages when needed, based on SPHINX_PATTERN, and not regex --- doc/source/conf.py | 29 ++++++++--------------------- 1 file changed, 8 insertions(+), 21 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 2174a797f0f2e..90fbc947a7f23 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -13,7 +13,6 @@ import sys import os -import re import inspect import importlib import logging @@ -100,14 +99,17 @@ exclude_patterns.append('**/*.ipynb') # sphinx_pattern can be '-api' to exclude the API pages, -# or the path to a file (e.g. '10min.rst' or 'generated/pandas.DataFrame.head.rst') +# or the path to a file +# (e.g. '10min.rst' or 'generated/pandas.DataFrame.head.rst') source_path = os.path.dirname(os.path.abspath(__file__)) pattern = os.environ.get('SPHINX_PATTERN') +autosummary_generate = pattern != '-api' if pattern: for dirname, dirs, fnames in os.walk(source_path): for fname in fnames: if os.path.splitext(fname)[-1] in ('.rst', '.ipynb'): - fname = os.path.relpath(os.path.join(dirname, fname), source_path) + fname = os.path.relpath(os.path.join(dirname, fname), + source_path) if (fname == 'index.rst' and os.path.abspath(dirname) == source_path): @@ -118,33 +120,18 @@ elif fname != pattern: exclude_patterns.append(fname) -print(exclude_patterns) - with open(os.path.join(source_path, 'index.rst.template')) as f: t = jinja2.Template(f.read()) - with open(os.path.join(source_path, 'index.rst'), 'w') as f: f.write(t.render(include_api=pattern is None, - single_doc=os.path.splitext(pattern)[0] - if pattern is not None and pattern != '-api' - else None)) + single_doc=(os.path.splitext(pattern)[0] + if pattern is not None and pattern != '-api' + else None))) spelling_word_list_filename = ['spelling_wordlist.txt', 'names_wordlist.txt'] spelling_ignore_pypi_package_names = True -with open("index.rst") as f: - index_rst_lines = f.readlines() - -# only include the slow autosummary feature if we're building the API section -# of the docs - -# JP: added from sphinxdocs -autosummary_generate = False - -if any(re.match(r"\s*api\s*", l) for l in index_rst_lines): - autosummary_generate = True - # numpydoc # for now use old parameter listing (styling + **kwargs problem) numpydoc_use_blockquotes = True From e851cae2d157f147ec45bca7d41df0b3fe9bcad8 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Tue, 25 Dec 2018 01:51:37 +0000 Subject: [PATCH 3/9] WIP simplifying doc build (pending not generate rst files from excluded api.rst) --- doc/make.py | 52 ++++++++++++++++------------------- doc/source/conf.py | 8 +----- doc/source/index.rst.template | 12 +++++--- 3 files changed, 33 insertions(+), 39 deletions(-) diff --git a/doc/make.py b/doc/make.py index 8c478876b39a5..8ea16323b9e8d 100755 --- a/doc/make.py +++ b/doc/make.py @@ -15,9 +15,8 @@ import sys import os import shutil -# import subprocess +import subprocess import argparse -from contextlib import contextmanager import webbrowser @@ -47,12 +46,11 @@ def __init__(self, num_jobs=1, include_api=True, single_doc=None, elif not include_api: os.environ['SPHINX_PATTERN'] = '-api' - # if self.single_doc_type == 'docstring': - # self._run_os('sphinx-autogen', os.path.join(SOURCE_PATH, 'index.rst')) - - if single_doc: + if single_doc and single_doc.endswith('.rst'): self.single_doc_html = os.path.splitext(single_doc)[0] + '.html' - + elif single_doc: + self.single_doc_html = 'generated/pandas.{}.html'.format( + single_doc) def _process_single_doc(self, single_doc): """ @@ -78,7 +76,7 @@ def _process_single_doc(self, single_doc): except AttributeError: raise ImportError('Could not import {}'.format(single_doc)) else: - return os.path.join('generated', '{}.rst'.format(single_doc)) + return single_doc[len('pandas.'):] else: raise ValueError('--single value should be a valid path to a ' '.rst or .ipynb file, or a valid pandas object ' @@ -98,14 +96,7 @@ def _run_os(*args): -------- >>> DocBuilder()._run_os('python', '--version') """ - # TODO check_call should be more safe, but it fails with - # exclude patterns, needs investigation - # subprocess.check_call(args, stderr=subprocess.STDOUT) - exit_status = os.system(' '.join(args)) - if exit_status: - msg = 'Command "{}" finished with exit code {}' - raise RuntimeError(msg.format(' '.join(args), exit_status)) - #subprocess.check_call(args, stderr=subprocess.STDOUT) + subprocess.check_call(args, stdout=sys.stdout, stderr=sys.stderr) def _sphinx_build(self, kind): """ @@ -125,21 +116,26 @@ def _sphinx_build(self, kind): raise ValueError('kind must be html or latex, ' 'not {}'.format(kind)) - self._run_os('sphinx-build', - '-j{}'.format(self.num_jobs), - '-b{}'.format(kind), - '-W' if self.warnings_are_errors else '', - '-{}'.format( - 'v' * self.verbosity) if self.verbosity else '', - '-d"{}"'.format(os.path.join(BUILD_PATH, 'doctrees')), - '"{}"'.format(SOURCE_PATH), - '"{}"'.format(os.path.join(BUILD_PATH, kind))) + self.clean() + + cmd = ['sphinx-build', '-b', kind] + if self.num_jobs: + cmd += ['-j', str(self.num_jobs)] + if self.warnings_are_errors: + cmd.append('-W') + if self.verbosity: + cmd.append('-{}'.format('v' * self.verbosity)) + cmd += ['-d', os.path.join(BUILD_PATH, 'doctrees'), + SOURCE_PATH, os.path.join(BUILD_PATH, kind)] + cmd = ['sphinx-build', SOURCE_PATH, os.path.join(BUILD_PATH, kind)] + self._run_os(*cmd) def _open_browser(self, single_doc_html): """ Open a browser tab showing single """ - url = os.path.join('file://', DOC_PATH, 'build', 'html', single_doc_html) + url = os.path.join('file://', DOC_PATH, 'build', 'html', + single_doc_html) webbrowser.open(url, new=2) def html(self): @@ -217,7 +213,7 @@ def main(): help='command to run: {}'.format(', '.join(cmds))) argparser.add_argument('--num-jobs', type=int, - default=1, + default=0, help='number of jobs used by sphinx-build') argparser.add_argument('--no-api', default=False, @@ -249,7 +245,7 @@ def main(): # external libraries (namely Sphinx) to compile this module and resolve # the import of `python_path` correctly. The latter is used to resolve # the import within the module, injecting it into the global namespace - os.environ['PYTHONPATH'] = args.python_path + #os.environ['PYTHONPATH'] = args.python_path sys.path.append(args.python_path) globals()['pandas'] = importlib.import_module('pandas') diff --git a/doc/source/conf.py b/doc/source/conf.py index 667b3e4273a98..b185905a5d37f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -114,16 +114,10 @@ t = jinja2.Template(f.read()) with open(os.path.join(source_path, 'index.rst'), 'w') as f: f.write(t.render(include_api=pattern is None, - single_doc=(os.path.splitext(pattern)[0] + single_doc=(pattern if pattern is not None and pattern != '-api' else None))) -# numpydoc -# for now use old parameter listing (styling + **kwargs problem) -numpydoc_use_blockquotes = True -# use member listing for attributes -numpydoc_attributes_as_param_list = False - # matplotlib plot directive plot_include_source = True plot_formats = [("png", 90)] diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index 7b2811f2146c5..7794f11c1b76f 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -106,17 +106,21 @@ Some other notes See the package overview for more detail about what's in the library. -{% if single_doc and single_doc.startswith('generated') -%} +{% if single_doc and single_doc.endswith('.rst') -%} +.. toctree:: + :maxdepth: 4 + + {{ single_doc[:-4] }} +{% elif single_doc %} .. autosummary:: :toctree: generated/ + + {{ single_doc }} {% else -%} .. toctree:: :maxdepth: 4 {% endif %} - {% if single_doc -%} - {{ single_doc }} - {% endif -%} {% if not single_doc -%} What's New install From fc9c359c86d449b5967070ff7fd9de0df5ef1a53 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Tue, 25 Dec 2018 22:03:09 +0000 Subject: [PATCH 4/9] Not generating all the api pages or the intersphinx db when a single page is built --- doc/make.py | 1 + doc/source/conf.py | 23 +++++++++++------------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/make.py b/doc/make.py index 8ea16323b9e8d..5841b040a2837 100755 --- a/doc/make.py +++ b/doc/make.py @@ -46,6 +46,7 @@ def __init__(self, num_jobs=1, include_api=True, single_doc=None, elif not include_api: os.environ['SPHINX_PATTERN'] = '-api' + self.single_doc_html = None if single_doc and single_doc.endswith('.rst'): self.single_doc_html = os.path.splitext(single_doc)[0] + '.html' elif single_doc: diff --git a/doc/source/conf.py b/doc/source/conf.py index b185905a5d37f..a79ee8939772e 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -93,7 +93,6 @@ # (e.g. '10min.rst' or 'generated/pandas.DataFrame.head.rst') source_path = os.path.dirname(os.path.abspath(__file__)) pattern = os.environ.get('SPHINX_PATTERN') -autosummary_generate = pattern != '-api' if pattern: for dirname, dirs, fnames in os.walk(source_path): for fname in fnames: @@ -117,6 +116,7 @@ single_doc=(pattern if pattern is not None and pattern != '-api' else None))) +autosummary_generate = True if pattern is None else ['index'] # matplotlib plot directive plot_include_source = True @@ -396,17 +396,16 @@ # latex_use_modindex = True -intersphinx_mapping = { - 'statsmodels': ('http://www.statsmodels.org/devel/', None), - 'matplotlib': ('https://matplotlib.org/', None), - 'pandas-gbq': ('https://pandas-gbq.readthedocs.io/en/latest/', None), - 'python': ('https://docs.python.org/3/', None), - 'numpy': ('https://docs.scipy.org/doc/numpy/', None), - 'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None), - 'py': ('https://pylib.readthedocs.io/en/latest/', None) -} -import glob -autosummary_generate = glob.glob("*.rst") +if pattern is None: + intersphinx_mapping = { + 'statsmodels': ('http://www.statsmodels.org/devel/', None), + 'matplotlib': ('https://matplotlib.org/', None), + 'pandas-gbq': ('https://pandas-gbq.readthedocs.io/en/latest/', None), + 'python': ('https://docs.python.org/3/', None), + 'numpy': ('https://docs.scipy.org/doc/numpy/', None), + 'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None), + 'py': ('https://pylib.readthedocs.io/en/latest/', None) + } # extlinks alias extlinks = {'issue': ('https://github.com/pandas-dev/pandas/issues/%s', From ade46e60d75cc501b3861d355a570c1d478f6304 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Tue, 25 Dec 2018 23:50:21 +0000 Subject: [PATCH 5/9] Restoring python path env --- doc/make.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/make.py b/doc/make.py index 5841b040a2837..d8cb6e52c5014 100755 --- a/doc/make.py +++ b/doc/make.py @@ -246,7 +246,7 @@ def main(): # external libraries (namely Sphinx) to compile this module and resolve # the import of `python_path` correctly. The latter is used to resolve # the import within the module, injecting it into the global namespace - #os.environ['PYTHONPATH'] = args.python_path + os.environ['PYTHONPATH'] = args.python_path sys.path.append(args.python_path) globals()['pandas'] = importlib.import_module('pandas') From 648da45c4d78155861041df89d53cf75fa06f38a Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Wed, 26 Dec 2018 00:00:03 +0000 Subject: [PATCH 6/9] Fixing comment with wrong info --- doc/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index a79ee8939772e..abafe32b44e54 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -89,8 +89,8 @@ exclude_patterns.append('**/*.ipynb') # sphinx_pattern can be '-api' to exclude the API pages, -# or the path to a file -# (e.g. '10min.rst' or 'generated/pandas.DataFrame.head.rst') +# the path to a file, or a Python object +# (e.g. '10min.rst' or 'pandas.DataFrame.head') source_path = os.path.dirname(os.path.abspath(__file__)) pattern = os.environ.get('SPHINX_PATTERN') if pattern: From c489aa625d7c8113adef1efa9338bd98b1f20839 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Wed, 26 Dec 2018 00:19:46 +0000 Subject: [PATCH 7/9] Removing not needed raw_input --- doc/source/conf.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index abafe32b44e54..576053d4335b6 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -24,11 +24,6 @@ logger = logging.getLogger(__name__) -try: - raw_input # Python 2 -except NameError: - raw_input = input # Python 3 - # https://github.com/sphinx-doc/sphinx/pull/2325/files # Workaround for sphinx-build recursion limit overflow: # pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL) From 55e47a28aef1cf6354d721c9c508e43f4e7d804a Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sat, 29 Dec 2018 15:46:01 +0000 Subject: [PATCH 8/9] Adding value to --single error message --- doc/make.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/make.py b/doc/make.py index d8cb6e52c5014..83a45ce3f981a 100755 --- a/doc/make.py +++ b/doc/make.py @@ -79,9 +79,10 @@ def _process_single_doc(self, single_doc): else: return single_doc[len('pandas.'):] else: - raise ValueError('--single value should be a valid path to a ' - '.rst or .ipynb file, or a valid pandas object ' - '(e.g. categorical.rst or pandas.DataFrame.head)') + raise ValueError(('--single={} not understood. Value should be a ' + 'valid path to a .rst or .ipynb file, or a ' + 'valid pandas object (e.g. categorical.rst or ' + 'pandas.DataFrame.head)').format(single_doc)) @staticmethod def _run_os(*args): From 44069881f3315906eb39dfa0b49880e92964240c Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sat, 29 Dec 2018 15:53:10 +0000 Subject: [PATCH 9/9] Changing num_jobs default value to 0 everywhere, to be consistent --- doc/make.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/make.py b/doc/make.py index 83a45ce3f981a..21ebd7303b50d 100755 --- a/doc/make.py +++ b/doc/make.py @@ -33,7 +33,7 @@ class DocBuilder: All public methods of this class can be called as parameters of the script. """ - def __init__(self, num_jobs=1, include_api=True, single_doc=None, + def __init__(self, num_jobs=0, include_api=True, single_doc=None, verbosity=0, warnings_are_errors=False): self.num_jobs = num_jobs self.verbosity = verbosity