Opened 6 years ago

Closed 6 years ago

Last modified 5 years ago

#12849 closed defect (fixed)

The argspecs of extension function/methods is broken in the Sphinx documentation

Reported by: hivert Owned by: mvngu, hivert
Priority: critical Milestone: sage-5.0
Component: documentation Keywords: argspecs Cython
Cc: Merged in: sage-5.0.beta14
Authors: Florent Hivert, Jeroen Demeyer Reviewers: Mike Hansen
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description (last modified by hivert)

In the current Sphinx HTML doc, the extenstion function and methods have no arguments setup.

See for example the documentation of

reference/sage/symbolic/expression.html#sage.symbolic.expression.Expression.N

which was ok (see there) in Sage 4.8. The problem was introduced in sage-5.0.beta8.

We should add a regression test on that kinds of problem.

Apply:

Attachments (2)

12849_doctest.patch (1.2 KB) - added by jdemeyer 6 years ago.
Doctest for the issue
trac_12849-extfunc_argspec_html_fix-fh.patch (672 bytes) - added by hivert 6 years ago.

Download all attachments as: .zip

Change History (23)

comment:1 Changed 6 years ago by hivert

  • Owner changed from mvngu to mvngu, hivert

Changed 6 years ago by jdemeyer

Doctest for the issue

comment:2 follow-up: Changed 6 years ago by jdemeyer

I created a doctest for this issue, which obviously fails on recent Sage betas.

comment:3 in reply to: ↑ 2 ; follow-up: Changed 6 years ago by hivert

Replying to jdemeyer:

I created a doctest for this issue, which obviously fails on recent Sage betas.

Thanks ! I tried to figureout a way to call directly Sphinx but this is much easier. I'll try to work on this this afternoon. Do you have somewhere the various beta compiled so that I can rsync them on boxen to help bissecting ? So far the few guesses I made to find the culprit were wrong.

comment:4 Changed 6 years ago by jdemeyer

sage-5.0.beta5 is still okay.

comment:5 in reply to: ↑ 3 Changed 6 years ago by jdemeyer

Replying to hivert:

Replying to jdemeyer:

I created a doctest for this issue, which obviously fails on recent Sage betas.

Thanks ! I tried to figureout a way to call directly Sphinx but this is much easier. I'll try to work on this this afternoon. Do you have somewhere the various beta compiled so that I can rsync them on boxen to help bissecting ? So far the few guesses I made to find the culprit were wrong.

Look at http://boxen.math.washington.edu/home/release/. There should be binaries for all Sage betas, made on sage.math or boxen.math.

comment:6 Changed 6 years ago by jdemeyer

  • Description modified (diff)

comment:7 Changed 6 years ago by hivert

It seems that I have a fix, but I don't understand how it worked before ! Still looking.

Florent

comment:8 Changed 6 years ago by jdemeyer

  • Description modified (diff)

It looks like this was introduced in sage-5.0.beta8.

comment:9 follow-up: Changed 6 years ago by jdemeyer

The culprit is #9128.

comment:10 in reply to: ↑ 9 Changed 6 years ago by hivert

Thanks for investigating.

Replying to jdemeyer:

The culprit is #9128.

Strange ! It was an obvious candidate and I'm pretty sure I started by checking this one. Still I don't understand what could cause that in #9128. I'm testing my fix.

Florent

comment:11 Changed 6 years ago by jdemeyer

  • Priority changed from blocker to critical

comment:12 Changed 6 years ago by hivert

Hi,

I got the fix ! I'm definitely the culprit. For strange reason the following lines were removed by #9128. Putting them back should fix the problem.

  • doc/common/conf.py

    diff --git a/doc/common/conf.py b/doc/common/conf.py
    a b def find_sage_dangling_links(app, env, n 
    576576    newnode.append(contnode)
    577577    return newnode
    578578
     579from sage.misc.sageinspect import sage_getargspec
     580autodoc_builtin_argspec = sage_getargspec
    579581
    580582def setup(app):
    581583    app.connect('autodoc-process-docstring', process_docstring_cython)

comment:13 Changed 6 years ago by hivert

  • Authors set to Florent Hivert, Jeroen Demeyer
  • Description modified (diff)
  • Status changed from new to needs_review

comment:14 follow-up: Changed 6 years ago by hivert

Jeroen: I'm reviewing your patch. Can you review mine ?

Florent

comment:15 in reply to: ↑ 14 Changed 6 years ago by jdemeyer

Replying to hivert:

Can you review mine ?

Sorry, no. I'm not at all familiar with the docbuilding process.

comment:16 follow-up: Changed 6 years ago by mhansen

  • Reviewers set to Mike Hansen
  • Status changed from needs_review to positive_review

Florent's patch is good, as is Jeroen (even if it is a bit sensitive to the particular HTML output used by Sphinx).

comment:17 in reply to: ↑ 16 Changed 6 years ago by hivert

Replying to mhansen:

Florent's patch is good, as is Jeroen (even if it is a bit sensitive to the particular HTML output used by Sphinx).

Thanks Mike !

comment:18 Changed 6 years ago by jdemeyer

  • Merged in set to sage-5.0.beta14
  • Resolution set to fixed
  • Status changed from positive_review to closed

comment:19 Changed 5 years ago by hthomas

Hi!

The doctest introduced by this patch, at line 22 of sage/misc/sagedoc.py, is causing the sagepad.org patchbot to fail on some (trivial, unrelated) patches. The problem seems to be that the doctest is trying to check the documentation when the documentation isn't built.

I don't know if this is really a problem with this patch, or with the patchbot, but I thought I would try reporting it here. If I should try elsewhere, please let me know!

You can see this failure at #12943, which is a completely trivial patch. (It's also making the sagepad.org patchbot fail on #10527. If you look at that ticket, though, don't look at the log for Volker's patchbot, which is having a different problem.)

cheers,

Hugh

comment:20 Changed 5 years ago by jhpalmieri

A complete set of documentation is an integral part of a Sage build, so doctests are supposed to fail if the documentation hasn't been built. This is not because of this ticket, I don't think.

comment:21 Changed 5 years ago by hthomas

Thanks. The issue seems to be with the particular patchbot -- I have posted to sage-devel about it.

Note: See TracTickets for help on using tickets.