Numpy documentation: status and distribution for 1.3.0
Hi,
For the upcoming 1.3.0 release, I would like to distribute the (built) documentation in some way. But first, I need to be able to build it :) What are the exact requirements to build the documentation ? Is sphinx 0.5 enough ? I can't manage to build it on either mac os x or linux:
... dumping search index... Exception occurred: File "/Users/david/local/stow/sphinx.dev/lib/python2.5/site-packages/sphinx/search.py", line 151, in get_descrefs pdict[name] = (fn2index[doc], i) KeyError: 'reference/c-api.types-and-structures' The full traceback has been saved in /var/folders/b-/b-BC2bPYFouYhoybrvprFE+++TI/-Tmp-/sphinx-err-PKglvL.log, if you want to report the issue to the author. Please also report this if it was a user error, so that a better error message can be provided next time.
There are also some errors on mac os x about too many opened files (which can be alleviated by running the make html again, but obviously, that's not great). I don't know if there are easy solutions to that problem,
cheers,
David
David Cournapeau wrote:
Hi,
For the upcoming 1.3.0 release, I would like to distribute the (built) documentation in some way. But first, I need to be able to build it :) What are the exact requirements to build the documentation ? Is sphinx 0.5 enough ? I can't manage to build it on either mac os x or linux:
David,
A few days ago I was trying to build it on linux. I could not build it with 0.5.1 or with 0.6dev. I submitted tickets to sphinx for the latter, and I think the first three problems were fixed before I hit one that required a change on the numpy side. I was not (and still am not) prepared to work on it, so that was the end of it.
http://www.mail-archive.com/numpy-discussion@scipy.org/msg15953.html
Eric
... dumping search index... Exception occurred: File "/Users/david/local/stow/sphinx.dev/lib/python2.5/site-packages/sphinx/search.py", line 151, in get_descrefs pdict[name] = (fn2index[doc], i) KeyError: 'reference/c-api.types-and-structures' The full traceback has been saved in /var/folders/b-/b-BC2bPYFouYhoybrvprFE+++TI/-Tmp-/sphinx-err-PKglvL.log, if you want to report the issue to the author. Please also report this if it was a user error, so that a better error message can be provided next time.
There are also some errors on mac os x about too many opened files (which can be alleviated by running the make html again, but obviously, that's not great). I don't know if there are easy solutions to that problem,
cheers,
David _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion
Tue, 10 Mar 2009 15:27:32 +0900, David Cournapeau wrote:
For the upcoming 1.3.0 release, I would like to distribute the (built) documentation in some way. But first, I need to be able to build it :)
Yep, buildability would be a nice feature :)
What are the exact requirements to build the documentation ? Is sphinx 0.5 enough ? I can't manage to build it on either mac os x or linux:
Sphinx 0.5.1 worksforme, and on two different Linux machines (and Python versions), so I doubt it's somehow specific to my setup.
Sphinx 0.6.dev doesn't work at the moment with autosummary. It's a bit of a moving target, so I haven't made keeping it working a priority.
dumping search index... Exception occurred: File "/Users/david/local/stow/sphinx.dev/lib/python2.5/site-packages/
sphinx/search.py",
line 151, in get_descrefs pdict[name] = (fn2index[doc], i) KeyError: 'reference/c-api.types-and-structures' The full traceback has been saved in /var/folders/b-/b-BC2bPYFouYhoybrvprFE+++TI/-Tmp-/sphinx-err-PKglvL.log, if you want to report the issue to the author. Please also report this if it was a user error, so that a better error message can be provided next time.
This is a Sphinx error I run into from time to time. Usually
make clean
helps, but I'm not sure what causes this. The error looks a bit like
http://bitbucket.org/birkenfeld/sphinx/issue/81/
but I think Ctrl+C is not a requirement for triggering it. Did you get this error from a clean build?
There are also some errors on mac os x about too many opened files (which can be alleviated by running the make html again, but obviously, that's not great). I don't know if there are easy solutions to that problem,
At which step did this error occur?
Tue, 10 Mar 2009 18:22:12 +0000, Pauli Virtanen wrote:
Tue, 10 Mar 2009 15:27:32 +0900, David Cournapeau wrote:
For the upcoming 1.3.0 release, I would like to distribute the (built) documentation in some way. But first, I need to be able to build it :)
Yep, buildability would be a nice feature :)
What are the exact requirements to build the documentation ? Is sphinx 0.5 enough ? I can't manage to build it on either mac os x or linux:
Sphinx 0.5.1 worksforme, and on two different Linux machines (and Python versions), so I doubt it's somehow specific to my setup.
One additional thing that needs to be taken care of is that
import numpy
in the python used to run Sphinx imports the version of numpy you want to generated documentation for.
On Wed, Mar 11, 2009 at 3:22 AM, Pauli Virtanen pav@iki.fi wrote:
Tue, 10 Mar 2009 15:27:32 +0900, David Cournapeau wrote:
For the upcoming 1.3.0 release, I would like to distribute the (built) documentation in some way. But first, I need to be able to build it :)
Yep, buildability would be a nice feature :)
Yes, indeed. Ideally, I would the doc to build on as many platforms as possible.
What are the exact requirements to build the documentation ? Is sphinx 0.5 enough ? I can't manage to build it on either mac os x or linux:
Sphinx 0.5.1 worksforme, and on two different Linux machines (and Python versions), so I doubt it's somehow specific to my setup.
Yes, it is strange - I can make it work on my workstation, which has the same distribution as my laptop (where it was failing). I am still unsure about the possible differences (sphinx version was of course the same).
Sphinx 0.6.dev doesn't work at the moment with autosummary. It's a bit of a moving target, so I haven't made keeping it working a priority.
Sure - I was actually afraid I needed sphinx 0.6.
This is a Sphinx error I run into from time to time. Usually
make clean
helps, but I'm not sure what causes this. The error looks a bit like
http://bitbucket.org/birkenfeld/sphinx/issue/81/
but I think Ctrl+C is not a requirement for triggering it. Did you get this error from a clean build?
Ah, that may be part of the problem. I can't make a clean build on mac os x, because of the "too many opened files" thing. Maybe mac os x has a ulimit kind of thing I should set up to avoid this.
There are also some errors on mac os x about too many opened files (which can be alleviated by running the make html again, but obviously, that's not great). I don't know if there are easy solutions to that problem,
At which step did this error occur?
It occurs at the html output phase ("writing output")- maybe there is a bug in sphinx with some files which are not closed properly.
Concerning the doc, I would like to add a few notes about the work we did for the C math lib: is it ok to add a chapter to the C reference guide, or is there a more appropriate place ?
cheers,
David
Wed, 11 Mar 2009 16:20:47 +0900, David Cournapeau wrote:
On Wed, Mar 11, 2009 at 3:22 AM, Pauli Virtanen pav@iki.fi wrote:
[clip]
Sphinx 0.5.1 worksforme, and on two different Linux machines (and Python versions), so I doubt it's somehow specific to my setup.
Yes, it is strange - I can make it work on my workstation, which has the same distribution as my laptop (where it was failing). I am still unsure about the possible differences (sphinx version was of course the same).
Did you check Pythonpath and egg-overriding-pythonpath issues? There's also some magic in the autosummary extension, but it's not *too* black, so I'd be surprised if it was behind these troubles.
[clip: Sphinx issue #81]
Ah, that may be part of the problem. I can't make a clean build on mac os x, because of the "too many opened files" thing. Maybe mac os x has a ulimit kind of thing I should set up to avoid this.
Perhaps it even has ulimit, being a sort of POSIX system?
Concerning the doc, I would like to add a few notes about the work we did for the C math lib: is it ok to add a chapter to the C reference guide, or is there a more appropriate place?
C reference guide is probably the correct place. Since the topic is a bit orthogonal to anything else there currently, I'd suggest creating a new file c-api.npymath.rst and linking it to the toctree in c-api.rst
Pauli Virtanen wrote:
Did you check Pythonpath and egg-overriding-pythonpath issues? There's also some magic in the autosummary extension, but it's not *too* black, so I'd be surprised if it was behind these troubles.
I think the problem boils down to building from scratch at once.
Perhaps it even has ulimit, being a sort of POSIX system?
Yes, and it works. I am not convinced it is not a bug in sphinx, but increasing from 256 to 1000 max files opened work.
C reference guide is probably the correct place. Since the topic is a bit orthogonal to anything else there currently, I'd suggest creating a new file c-api.npymath.rst and linking it to the toctree in c-api.rst
That's what I ended up doing.
Thanks, now I can build the doc on windows, mac os x and linux,
David
participants (4)
-
David Cournapeau -
David Cournapeau -
Eric Firing -
Pauli Virtanen