DOC: docs don't build with new Sphinx version 1.2 #5899
Comments
|
@pv Do you know if you also have this issue with numpy? (Because I copied the approach of the class.rst template from the numpy docs) |
ghost
mentioned this issue
|
OK, this was a regression in Sphinx 1.2, and already solved in development version of Sphinx: https://bitbucket.org/birkenfeld/sphinx/issue/1335/numpy-docs-fail-to-build-with-sphinx-12 It seems they don't have concrete plans yet for a bugfix release: https://groups.google.com/forum/#!topic/sphinx-dev/QZe79WrWFnk |
|
@y-p And it seems this can be marked as solved soon! https://groups.google.com/forum/?fromgroups#!topic/sphinx-dev/QZe79WrWFnk |
|
Good show. Now we need to figure out why autosummary is so painfully slow |
|
http://sphinx-doc.org/changes.html Sphinx 1.2.1 is released and up on pypi. I will just mention it in #5996 and then this can be closed. |
|
1.2.1 throws a bunch of errors during build that neither 1.1.3 nor 1.3a0 raise it seems. |
|
@y-p What kind of errors? I tried and didn't see any (apart from some But with looking more closely now at the resulting api.html, I see a big difference in the output of autosummary. The determination of the summary lines seems to have changed (and not working well for pandas), as now for some functions multiple lines (even with the parameter explanations) are included in the autosummary tables. I think this has something to do with the first sentence that had to end with a |
I don't see these with 1.3.0 or 1.1.3, but maybe I forgot a step when checking. In recent work on docs I've noticed that our docstrings, PEP 257 defines some rules for docstring handling tools that cleans up |
|
Now that I think of it, I wonder how much of the time it takes to import pandas is spent |
|
Cool. TIL slow function decorators impose a cost at import-time: a.py def foo(f):
import time
time.sleep(5)
return f
@foo
def f():
return 1It's obvious once you think of it, but I never did before. I guess that's similar to why js jockies precompile their templates. Update: dosn't make much of a difference for pandas though, I guess the work is elsewhere. |
|
@y-p The errors you see, I would think they have to do with your pandas itself, and not sphinx, as the tracebacks all lead to pandas. E.g. this one: is an error that occured when running the code in the example in basic.html at input prompt 127. This runs fine on my computer, but you seem to get an error. But due to pandas, not sphinx (as sphinx has in se nothing to do with the running of our code examples in the docs). So they seem not related to sphinx 1.2.1/1.1.3 version issues? |
|
@jorisvandenbossche this is a new function in 0.13.1 (didn't exist in 0.13). I think that sphinx is not picking up the new version function (I have to basically force it using an explicity path in: not sure how you guys get around this problem |
|
@jreback I am just working in a conda environment with pandas master, and when running Sphinx it picks up that version when importing pandas as should be. E.g. you can put In every case, reopening, as there is certainly an issue with |
|
@jreback if I understand what you describe correctly, that's what |
|
hmm will try develop |
|
strange, strange, now I am seeing the same issue. Never had this before. @y-p @jreback The issue you both reported with the doc building (y-p: I never had problems with this (just always used Any thoughts? |
|
how does sphinx know where to pick up pandas? e.g. you normally go to a sub-dir |
|
@jreback isn't it just the pandas you get if you would run |
|
I do this: main pandas repo to build to make docs so I am NOT in the same dir when I build the docs |
|
And what I normally do: I have a conda environment for development with all latest version, which is activated (comparable to virtualenv I think), then in main repo of pandas ( Because of the For building the docs, I just do: I never modified |
|
so must be some change in develop then? |
|
I don't have a venv, I just ran develop once and Try Do you still get issues? |
|
no, ok, solved it. In every case, now it works again. Why it failed I not fully sure, but I think it has something to do with that I installed the new version of Sphinx 1.2.1 with pip, and installed back again 1.1.3, but the sphinx-build-script.py was not updated, and for some reason, because of that it was picking a wrong version of pandas. |
|
But @jreback, if you use |
|
@y-p Do you still see the issues you reported above? #5899 (comment) |
|
@jorisvandenbossche yep...will give develop a try |
|
Nope, it works here now. |
|
OK, good to hear. So then there is only an issue with autosummary in the new Sphinx version 1.2.1. |
|
@y-p @jreback Something else, recently I am getting the following warning when building the docs I get this for: which are all attributes that are initialised as None (so Any of you seen this? |
|
And back to the original issue, for clarity I will leave this closed (as the original issue reported is solved with the release of 1.2.1) and open a new issue for the autosummary issue of the new sphinx. |
|
none of those attributes are new as u said |
I always build the docs with Sphinx 1.1.3, but recently (in december) a new Sphinx version was released: 1.2.
And it seems that the docs won't build with this new version (also mentioned in #5530 and #5701 (comment)). You get the following error:
This has something to do with the class.rst template for autosummary (which we extend in doc/source/_templates/autosummary/class.rst)
If you remove the template class.rst, the docs will build (you only will get a bunch of warnings because of links to non-existing documents, because not all docstring pages are built (that was the reason for the template)).
The text was updated successfully, but these errors were encountered: