Skip to content

DOC/CI: include api docs on travis #11069

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 6 commits into from
Closed

DOC/CI: include api docs on travis #11069

wants to merge 6 commits into from

Conversation

jorisvandenbossche
Copy link
Member

Continued in #12002

Closes #6100
Closes #3800

Just to check how this takes on travis

shoyer
shoyer reviewed Sep 12, 2015
View reviewed changes
doc/source/api.rst
@@ -978,7 +978,7 @@ specific plotting methods of the form ``DataFrame.plot.<kind>``.

.. autosummary::
:toctree: generated/
:template: autosummary/accessor_plot.rst
:template: autosummary/accessor_callable.rst
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oops! looks like this snuck through before

@jreback
Copy link
Contributor

jreback commented Sep 13, 2015

might simply want to create a doc-build (e.g. this issue #3800)

@jreback jreback added Docs CI Continuous Integration Testing pandas testing functions or related to the test suite labels Sep 13, 2015
@jorisvandenbossche
Copy link
Member Author

@jreback yes, I know, but I was first just experimenting a bit to get it working (not very familiar with travis/bash syntax details). Once I have something working the idea was indeed to put it in a separate travis build.

The problem I have now, is that for some reason make.py does not output its progress to the standard output of travis (which is the case if you run it locally in a terminal). And then, because of this, travis thinks nothing is happening anymore and aborts the build ..
Do you know a solution for this?

@jreback
Copy link
Contributor

jreback commented Sep 13, 2015

http://docs.travis-ci.com/user/build-timeouts/

might work

@jreback
Copy link
Contributor

jreback commented Sep 13, 2015

is make.py writing to stderr? then could just redirect

maybe it's buffering?

@jreback
Copy link
Contributor

jreback commented Sep 13, 2015

https://coderwall.com/p/wws2uq/have-travis-ci-test-your-sphinx-docs

?

@jreback
Copy link
Contributor

jreback commented Sep 13, 2015

https://github.com/Syntaf/travis-sphinx

@jorisvandenbossche jorisvandenbossche force-pushed the travis-full-doc branch 2 times, most recently from 6150518 to 936069e Compare September 14, 2015 22:26
@jorisvandenbossche
Copy link
Member Author

make.py calls sphinx-build, which AFAIU outputs to both stdout as stderr? And also, I would think travis outputs both stdout as stderr in the logs? But it is not really clear to me how it is specified the output of the doc build is logged in a file that is then later shown, and why for tests it is outputted directly.

The travis_wait is probably not a solution, as this just raises the timeout from 10 to 20 minutes, but I think the doc build will even take longer.

@jorisvandenbossche
Copy link
Member Author

aha, hadn't notices that there is also a separate run_build_docs.sh script next to build_docs.sh, and that is of course capturing that output ..

@jorisvandenbossche jorisvandenbossche force-pushed the travis-full-doc branch 5 times, most recently from 93bf54f to 7eb2a8e Compare September 15, 2015 12:44
@jorisvandenbossche jorisvandenbossche force-pushed the travis-full-doc branch 6 times, most recently from 03d41f5 to 9512ed6 Compare September 27, 2015 09:03
@jorisvandenbossche
Copy link
Member Author

@jreback With the last commit the full docs build OK, although it took 37 minutes. So I put it in a separate travis build, and include the full api docs (there is still a temporary commit to let the others fail).

Can you have a look at the travis ci changes? (it also included somes hacks to numpydoc to prevent some warnings, they are not very nice hacks, but the warnings had to be eliminated to get it running on travis (otherwise the log was too big ..)).

jreback
jreback reviewed Sep 28, 2015
View reviewed changes
.travis.yml
@@ -18,6 +18,7 @@ git:

matrix:
fast_finish: true
fail_fast: true
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually don't think we should have this and leave it false. That way you can see the full gamut of errors (of course for your testsing ok)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, this one is from the temporary commit just for testing, will remove it

jreback
jreback reviewed Sep 28, 2015
View reviewed changes
ci/script.sh
@@ -4,6 +4,10 @@ echo "inside $0"

source activate pandas

if [ x"$DOC_BUILD" != x"" ]; then
exit 0
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for testing?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this one is on purpose and not for testing, so that the doc build does not run the tests (only the docs)

@jreback
Copy link
Contributor

jreback commented Sep 28, 2015

@jorisvandenbossche all looks cool to me then. I know the doc-build takes a while but so what its in the lower section.

note - the builds run in the order that they are defined in the top section (no matter if they are in th ebottom section or not). So you prob want to have the doc-build run last? (I think you have it that way). That way other workers can finish the other jobs. we can have 5 simultaneously i think.

@jorisvandenbossche
DOC/CI: include api docs on travis
f216c8e
@jorisvandenbossche
temp: let other fail
902f1ca
@jorisvandenbossche
DOC: hack to numpydoc to avoid warnings for Categorical (not includin…
8c42834 
…g 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.
@jorisvandenbossche
DOC: add str accessor docstring pages to api.rst to avoid warning
347b616
@jorisvandenbossche
DOC: hack to numpydoc to include attributes that are None (GH6100)
556b085 
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.
@jorisvandenbossche jorisvandenbossche mentioned this pull request Oct 7, 2015
Merged
@jorisvandenbossche
Copy link
Member Author

The problem with this approach is that the time it takes to build on Travis seems rather variable (maybe depending on its load?). In any case, sometimes it succeeded to finish it in ca 45 min, but other times it goes up to 50min and then travis aborts it.
But now trying if parallel build speeds it up

@jreback
Copy link
Contributor

jreback commented Nov 20, 2015

@jorisvandenbossche closing, but reopen if updating

in theory this looks like a great idea....but yeh it takes quite some time to build the API docs

@jreback jreback closed this Nov 20, 2015
@jorisvandenbossche jorisvandenbossche mentioned this pull request Jan 8, 2016
Closed
1 task
@jorisvandenbossche
Copy link
Member Author

Continued in #12002

jorisvandenbossche added a commit that referenced this pull request Jan 24, 2016
@jorisvandenbossche
DOC/CI: include api docs on travis
1330b9f 
Continuation of #11069 (It seems I cannot reopen that PR because I
already force pushed the branch ..)    Closes #3800    TODO:    - [x]
remove printing of doc build log file in after_script

Author: Joris Van den Bossche <[email protected]>

Closes #12002 from jorisvandenbossche/travis-full-doc and squashes the following commits:

2aaa92d [Joris Van den Bossche] DOC fixes
d9af945 [Joris Van den Bossche] Install latest sphinx version with pip
c8e58b0 [Joris Van den Bossche] DOC/CI: include api docs on travis
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
CI Continuous Integration Docs Testing pandas testing functions or related to the test suite
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@jorisvandenbossche @jreback @shoyer