documentation build error

Development matplotlib-devel
1

Hello,

The trunk is giving the following error while trying to build the documentation via “python make.py all”

reading sources… [ 4%] api/mlab_api
reST markup error:
/home/gsever/Desktop/python-repo/matplotlib/lib/matplotlib/mlab.py:docstring of matplotlib.mlab.cohere_pairs:6: (SEVERE/4) Unexpected section title.

A similar error reported at:

http://groups.google.com/group/sphinx-dev/browse_thread/thread/300153957f2902f9?pli=1

however, couldn’t figure to fix the issue.

Any comments?

···

–
Gökhan

2

OK,

Here comes a self fix:

http://svn.scipy.org/svn/numpy/trunk/doc/sphinxext/docscrape.py
http://svn.scipy.org/svn/numpy/trunk/doc/sphinxext/docscrape_sphinx.py
http://svn.scipy.org/svn/numpy/trunk/doc/sphinxext/numpydoc.py

added the above files under /doc/sphinxext and updated conf.py.

Then works.

This said, I am not sure is this the natural way to fix this problem?

Thanks.

···

On Tue, Aug 25, 2009 at 1:10 PM, Gökhan Sever <gokhansever@…149…> wrote:

Hello,

The trunk is giving the following error while trying to build the documentation via “python make.py all”

reading sources… [ 4%] api/mlab_api

reST markup error:
/home/gsever/Desktop/python-repo/matplotlib/lib/matplotlib/mlab.py:docstring of matplotlib.mlab.cohere_pairs:6: (SEVERE/4) Unexpected section title.

A similar error reported at:

http://groups.google.com/group/sphinx-dev/browse_thread/thread/300153957f2902f9?pli=1

however, couldn’t figure to fix the issue.

Any comments?

–
Gökhan

–
Gökhan

3

The error is caused by recent versions of Sphinx being more picky about headers in docstrings. I had to update my version of Sphinx in order to reproduce your error.

Your fix is adding support for Numpy's custom docstring format? I'm not sure we want to go down that road just yet. Easier to just remove the headers in the cohere_pairs docstring (since it's the only one!) and move on. I'll have a fix for this once my doc build is done.

I'm not saying using the Numpy format wouldn't be a good idea. But it's a lot of manual labor to move to that format, make sure things are consistent etc. It's interesting that your fix doesn't produce new problems, though.

Mike

Gökhan Sever wrote:

···

OK,

Here comes a self fix:

http://svn.scipy.org/svn/numpy/trunk/doc/sphinxext/docscrape.py
http://svn.scipy.org/svn/numpy/trunk/doc/sphinxext/docscrape_sphinx.py
http://svn.scipy.org/svn/numpy/trunk/doc/sphinxext/numpydoc.py

added the above files under /doc/sphinxext and updated conf.py.

Then works.

This said, I am not sure is this the natural way to fix this problem?

Thanks.

On Tue, Aug 25, 2009 at 1:10 PM, Gökhan Sever <gokhansever@...149... > <mailto:gokhansever@…149…>> wrote:

    Hello,

    The trunk is giving the following error while trying to build the
    documentation via "python make.py all"

    reading sources... [ 4%]
    api/mlab_api

    reST markup error:
    /home/gsever/Desktop/python-repo/matplotlib/lib/matplotlib/mlab.py:docstring
    of matplotlib.mlab.cohere_pairs:6: (SEVERE/4) Unexpected section
    title.

    A similar error reported at:

    http://groups.google.com/group/sphinx-dev/browse_thread/thread/300153957f2902f9?pli=1

    however, couldn't figure to fix the issue.

    Any comments?

    -- Gökhan

--
Gökhan
------------------------------------------------------------------------

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day trial. Simplify your report design, integration and deployment - and focus on what you do best, core application coding. Discover what's new with Crystal Reports now. http://p.sf.net/sfu/bobj-july
------------------------------------------------------------------------

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
matplotlib-devel List Signup and Options
  
--
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

4

Hmm,

That might be nothing to do with Sphinx’s being very recent. Since that thread from sphinx-dev list is from Oct 2008 and the guy reporting the similar issue seemingly using an even older Sphinx version (4.3)

I don’t exactly know what would be the advantage of making docstrings numpy standardized.

···

On Tue, Aug 25, 2009 at 3:01 PM, Michael Droettboom <mdroe@…31…> wrote:

The error is caused by recent versions of Sphinx being more picky about headers in docstrings. I had to update my version of Sphinx in order to reproduce your error.

Your fix is adding support for Numpy’s custom docstring format? I’m not sure we want to go down that road just yet. Easier to just remove the headers in the cohere_pairs docstring (since it’s the only one!) and move on. I’ll have a fix for this once my doc build is done.

I’m not saying using the Numpy format wouldn’t be a good idea. But it’s a lot of manual labor to move to that format, make sure things are consistent etc. It’s interesting that your fix doesn’t produce new problems, though.

Mike

Gökhan Sever wrote:

OK,

Here comes a self fix:

http://svn.scipy.org/svn/numpy/trunk/doc/sphinxext/docscrape.py

http://svn.scipy.org/svn/numpy/trunk/doc/sphinxext/docscrape_sphinx.py

http://svn.scipy.org/svn/numpy/trunk/doc/sphinxext/numpydoc.py

added the above files under /doc/sphinxext and updated conf.py.

Then works.

This said, I am not sure is this the natural way to fix this problem?

Thanks.

On Tue, Aug 25, 2009 at 1:10 PM, Gökhan Sever <gokhansever@…149… mailto:gokhansever@...552...149...> wrote:

Hello,



The trunk is giving the following error while trying to build the

documentation via "python make.py all"



reading sources... [  4%]

api/mlab_api                                                                            

reST markup error:

/home/gsever/Desktop/python-repo/matplotlib/lib/matplotlib/mlab.py:docstring

of matplotlib.mlab.cohere_pairs:6: (SEVERE/4) Unexpected section

title.



A similar error reported at:



[http://groups.google.com/group/sphinx-dev/browse_thread/thread/300153957f2902f9?pli=1](http://groups.google.com/group/sphinx-dev/browse_thread/thread/300153957f2902f9?pli=1)



however, couldn't figure to fix the issue.



Any comments?



--    Gökhan

–

Gökhan

Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day trial. Simplify your report design, integration and deployment - and focus on what you do best, core application coding. Discover what’s new with Crystal Reports now. http://p.sf.net/sfu/bobj-july

Matplotlib-devel mailing list

Matplotlib-devel@lists.sourceforge.net

https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

–

Michael Droettboom

Science Software Branch

Operations and Engineering Division

Space Telescope Science Institute

Operated by AURA for NASA

–
Gökhan