From f216c8e0b83f4240700db90afd2a97f7af027f87 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sat, 12 Sep 2015 10:52:30 +0200 Subject: [PATCH 1/6] DOC/CI: include api docs on travis --- .travis.yml | 17 +++++++++++++++-- ci/build_docs.sh | 11 +++++------ ci/requirements-2.7_DOC_BUILD.build | 4 ++++ ci/requirements-2.7_DOC_BUILD.run | 16 ++++++++++++++++ ci/run_build_docs.sh | 2 +- ci/script.sh | 5 +++++ 6 files changed, 46 insertions(+), 9 deletions(-) create mode 100644 ci/requirements-2.7_DOC_BUILD.build create mode 100644 ci/requirements-2.7_DOC_BUILD.run diff --git a/.travis.yml b/.travis.yml index 4e46fb7ad85ca..e15077a9b61a6 100644 --- a/.travis.yml +++ b/.travis.yml @@ -42,7 +42,6 @@ matrix: - FULL_DEPS=true - CLIPBOARD_GUI=gtk2 - BUILD_TYPE=conda - - DOC_BUILD=true # if rst files were changed, build docs in parallel with tests - python: 3.4 env: - JOB_NAME: "34_nslow" @@ -103,6 +102,13 @@ matrix: - NUMPY_BUILD=master - BUILD_TYPE=pydata - PANDAS_TESTING_MODE="deprecate" + - python: 2.7 + env: + - JOB_NAME: "doc_build" + - FULL_DEPS=true + - BUILD_TYPE=conda + - DOC_BUILD=true # if rst files were changed, build docs in parallel with tests + - JOB_TAG=_DOC_BUILD allow_failures: - python: 3.3 env: @@ -150,6 +156,13 @@ matrix: - FULL_DEPS=true - BUILD_TYPE=pydata - BUILD_TEST=true + - python: 2.7 + env: + - JOB_NAME: "doc_build" + - FULL_DEPS=true + - BUILD_TYPE=conda + - DOC_BUILD=true + - JOB_TAG=_DOC_BUILD before_install: - echo "before_install" @@ -178,7 +191,7 @@ before_script: script: - echo "script" - - ci/run_build_docs.sh & + - ci/run_build_docs.sh - ci/script.sh # nothing here, or failed tests won't fail travis diff --git a/ci/build_docs.sh b/ci/build_docs.sh index a8488e202dbec..c0843593f85ff 100755 --- a/ci/build_docs.sh +++ b/ci/build_docs.sh @@ -14,23 +14,22 @@ fi if [ x"$DOC_BUILD" != x"" ]; then - # we're running network tests, let's build the docs in the meantime echo "Will build docs" - conda install -n pandas sphinx=1.1.3 pygments ipython=2.4 --yes source activate pandas + conda install -n pandas -c r r rpy2 --yes + + time sudo apt-get $APT_ARGS install dvipng mv "$TRAVIS_BUILD_DIR"/doc /tmp cd /tmp/doc - rm /tmp/doc/source/api.rst # no R - rm /tmp/doc/source/r_interface.rst # no R - echo ############################### echo # Log file for the doc build # echo ############################### - echo -e "y\n" | ./make.py --no-api 2>&1 + echo ./make.py + ./make.py cd /tmp/doc/build/html git config --global user.email "pandas-docs-bot@localhost.foo" diff --git a/ci/requirements-2.7_DOC_BUILD.build b/ci/requirements-2.7_DOC_BUILD.build new file mode 100644 index 0000000000000..faf1e3559f7f1 --- /dev/null +++ b/ci/requirements-2.7_DOC_BUILD.build @@ -0,0 +1,4 @@ +dateutil +pytz +numpy +cython diff --git a/ci/requirements-2.7_DOC_BUILD.run b/ci/requirements-2.7_DOC_BUILD.run new file mode 100644 index 0000000000000..15634f7bb033b --- /dev/null +++ b/ci/requirements-2.7_DOC_BUILD.run @@ -0,0 +1,16 @@ +sphinx=1.2.3 +ipython=3.2.1 +matplotlib +scipy +lxml +beautiful-soup +html5lib +pytables +openpyxl=1.8.5 +xlrd +xlwt +xlsxwriter +sqlalchemy +numexpr +bottleneck +statsmodels diff --git a/ci/run_build_docs.sh b/ci/run_build_docs.sh index c04c815297aa3..2909b9619552e 100755 --- a/ci/run_build_docs.sh +++ b/ci/run_build_docs.sh @@ -2,7 +2,7 @@ echo "inside $0" -"$TRAVIS_BUILD_DIR"/ci/build_docs.sh 2>&1 > /tmp/doc.log & +"$TRAVIS_BUILD_DIR"/ci/build_docs.sh 2>&1 # wait until subprocesses finish (build_docs.sh) wait diff --git a/ci/script.sh b/ci/script.sh index 1126e8249646c..b2e02d27c970b 100755 --- a/ci/script.sh +++ b/ci/script.sh @@ -4,6 +4,11 @@ echo "inside $0" source activate pandas +# don't run the tests for the doc build +if [ x"$DOC_BUILD" != x"" ]; then + exit 0 +fi + if [ -n "$LOCALE_OVERRIDE" ]; then export LC_ALL="$LOCALE_OVERRIDE"; echo "Setting LC_ALL to $LOCALE_OVERRIDE" From 902f1cadf5faa7e36d6690b2f242b931fa844006 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 24 Sep 2015 16:22:35 +0200 Subject: [PATCH 2/6] temp: let other fail --- .travis.yml | 7 +++---- ci/before_install.sh | 4 ++++ 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.travis.yml b/.travis.yml index e15077a9b61a6..bd3b3bad6b73f 100644 --- a/.travis.yml +++ b/.travis.yml @@ -18,6 +18,7 @@ git: matrix: fast_finish: true + fail_fast: true include: - python: 2.6 env: @@ -105,10 +106,9 @@ matrix: - python: 2.7 env: - JOB_NAME: "doc_build" - - FULL_DEPS=true + - JOB_TAG=_DOC_BUILD - BUILD_TYPE=conda - DOC_BUILD=true # if rst files were changed, build docs in parallel with tests - - JOB_TAG=_DOC_BUILD allow_failures: - python: 3.3 env: @@ -159,10 +159,9 @@ matrix: - python: 2.7 env: - JOB_NAME: "doc_build" - - FULL_DEPS=true + - JOB_TAG=_DOC_BUILD - BUILD_TYPE=conda - DOC_BUILD=true - - JOB_TAG=_DOC_BUILD before_install: - echo "before_install" diff --git a/ci/before_install.sh b/ci/before_install.sh index e4376e1bf21c2..46f9507801330 100755 --- a/ci/before_install.sh +++ b/ci/before_install.sh @@ -11,3 +11,7 @@ echo "inside $0" sudo apt-get update $APT_ARGS # run apt-get update for all versions true # never fail because bad things happened here + +if [ x"$DOC_BUILD" == x"" ]; then + exit 1 +fi From 8c4283420451eb74f105ab9daf9f6358c0e0f31e Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sat, 26 Sep 2015 12:29:56 +0200 Subject: [PATCH 3/6] DOC: hack to numpydoc to avoid warnings for Categorical (not including members) The Categorical docstring in api.rst uses a seperate template to not include an autosummary table with toctrees of all members. But numpydoc still includes a list by default (which will gives thousands of warnings). This hack ensures that for Categorical class docstring this list is not included. --- doc/sphinxext/numpydoc/docscrape_sphinx.py | 3 ++- doc/sphinxext/numpydoc/numpydoc.py | 4 ++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/sphinxext/numpydoc/docscrape_sphinx.py b/doc/sphinxext/numpydoc/docscrape_sphinx.py index ba93b2eab779d..b103da80a8d23 100755 --- a/doc/sphinxext/numpydoc/docscrape_sphinx.py +++ b/doc/sphinxext/numpydoc/docscrape_sphinx.py @@ -19,6 +19,7 @@ def __init__(self, docstring, config={}): def load_config(self, config): self.use_plots = config.get('use_plots', False) self.class_members_toctree = config.get('class_members_toctree', True) + self.class_members_list = config.get('class_members_list', True) # string conversion routines def _str_header(self, name, symbol='`'): @@ -95,7 +96,7 @@ def _str_member_list(self, name): """ out = [] - if self[name]: + if self[name] and self.class_members_list: out += ['.. rubric:: %s' % name, ''] prefix = getattr(self, '_name', '') diff --git a/doc/sphinxext/numpydoc/numpydoc.py b/doc/sphinxext/numpydoc/numpydoc.py index 2bc2d1e91ed3f..0cccf72de3745 100755 --- a/doc/sphinxext/numpydoc/numpydoc.py +++ b/doc/sphinxext/numpydoc/numpydoc.py @@ -42,6 +42,10 @@ def mangle_docstrings(app, what, name, obj, options, lines, class_members_toctree=app.config.numpydoc_class_members_toctree, ) + # PANDAS HACK (to remove the list of methods/attributes for Categorical) + if what == "class" and name.endswith(".Categorical"): + cfg['class_members_list'] = False + if what == 'module': # Strip top title title_re = re.compile(sixu('^\\s*[#*=]{4,}\\n[a-z0-9 -]+\\n[#*=]{4,}\\s*'), From 347b616f77976db93b3b8cc48d99146b5f47552b Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sat, 26 Sep 2015 13:01:12 +0200 Subject: [PATCH 4/6] DOC: add str accessor docstring pages to api.rst to avoid warning --- doc/source/api.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index 60516fd02b116..ca6874ecbf24a 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -603,7 +603,7 @@ strings and apply several methods to it. These can be acccessed like .. The following is needed to ensure the generated pages are created with the - correct template (otherwise they would be created in the Series class page) + correct template (otherwise they would be created in the Series/Index class page) .. .. autosummary:: @@ -613,6 +613,10 @@ strings and apply several methods to it. These can be acccessed like Series.str Series.cat Series.dt + Index.str + CategoricalIndex.str + DatetimeIndex.str + TimedeltaIndex.str .. _api.categorical: From 556b085c3403ad4ef4bda983f0508018ff9a5f75 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sat, 26 Sep 2015 14:23:11 +0200 Subject: [PATCH 5/6] DOC: hack to numpydoc to include attributes that are None (GH6100) See GH6100. Some attributes of our classes are None, even on the class objects themselves (so not on instances). By default, numpydoc does not include them in the autosummary table but in a separate plain table. But, our class.rst template does include them in the toctree autosummary, which creates docstring pages for these. This results in warnings "WARNING: document isn't included in any toctree". This hack to numpydoc does include them in the autosummary in the class docstring, removing this warning. --- doc/sphinxext/numpydoc/docscrape_sphinx.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/sphinxext/numpydoc/docscrape_sphinx.py b/doc/sphinxext/numpydoc/docscrape_sphinx.py index b103da80a8d23..5a582b4d03282 100755 --- a/doc/sphinxext/numpydoc/docscrape_sphinx.py +++ b/doc/sphinxext/numpydoc/docscrape_sphinx.py @@ -115,11 +115,13 @@ def _str_member_list(self, name): or inspect.isgetsetdescriptor(param_obj)): param_obj = None - if param_obj and (pydoc.getdoc(param_obj) or not desc): - # Referenced object has a docstring - autosum += [" %s%s" % (prefix, param)] - else: - others.append((param, param_type, desc)) + # pandas HACK - do not exclude attributes wich are None + # if param_obj and (pydoc.getdoc(param_obj) or not desc): + # # Referenced object has a docstring + # autosum += [" %s%s" % (prefix, param)] + # else: + # others.append((param, param_type, desc)) + autosum += [" %s%s" % (prefix, param)] if autosum: out += ['.. autosummary::'] From 58d32306a048f7b5fd66423313f8fc98762055ff Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Wed, 7 Oct 2015 12:50:10 +0200 Subject: [PATCH 6/6] DOC: parallel build --- doc/make.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/make.py b/doc/make.py index 6b424ce2814d5..b6e2cc90b620d 100755 --- a/doc/make.py +++ b/doc/make.py @@ -104,7 +104,7 @@ def clean(): def html(): check_build() - if os.system('sphinx-build -P -b html -d build/doctrees ' + if os.system('sphinx-build -P -j 4 -b html -d build/doctrees ' 'source build/html'): raise SystemExit("Building HTML failed.") try: