Opened 8 years ago

Closed 8 years ago

#13116 closed defect (fixed)

The :trac: sphinx role does not work on the commandline

Reported by: vbraun Owned by: mvngu
Priority: major Milestone: sage-5.1
Component: documentation Keywords: sd41
Cc: hivert, kcrisman, jhpalmieri Merged in: sage-5.1.beta6
Authors: John Palmieri Reviewers: Volker Braun
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description

#12490 introduced a :trac:12490 role to sphinx, which is typeset into "trac ticket #<hyperlink>". But it does not work on the command line:

sage: sage.rings.qqbar?
[...]
    TESTS:
    
    Verify that >>:trac:`10981`<< is fixed: 

It should also typeset into a trac link on the command line.

To shorten the urls as much as possible, it would be nice to be able to just say http://trac.sagemath.org/12490. It would be easy to do with mod_rewrite.

Attachments (1)

trac_13116-trac-docstring.patch (3.9 KB) - added by jhpalmieri 8 years ago.
Sage library

Download all attachments as: .zip

Change History (15)

comment:1 Changed 8 years ago by kcrisman

  • Cc kcrisman added

comment:2 Changed 8 years ago by jhpalmieri

  • Cc jhpalmieri added

comment:3 Changed 8 years ago by jhpalmieri

Does this even work in the notebook? It doesn't for me: I only see it working successfully in the reference manual.

comment:4 Changed 8 years ago by vbraun

Indeed, I should have said that it works in the typeset manual only.

On a related note, it sucks that sage.misc.sagedoc calls into sagenb stuff to do the sphinxification. IHMO this should be pulled into the Sage library, the notebook can publish a hook for the documentation formatter of choice.

comment:5 Changed 8 years ago by jhpalmieri

  • Authors set to John Palmieri
  • Status changed from new to needs_review

Here's a patch which fixes the problem for me, dealt with along the lines of similar issues in sage.misc.sagedoc.

comment:6 Changed 8 years ago by kcrisman

My only fear is that this will make a lot of stuff look really long and crazy in the command line, wrapping etc. What do the examples look like in the command line now?

comment:7 Changed 8 years ago by jhpalmieri

Here's a version using the shortened urls discussed in sage-devel.

Typing sage.misc.sagedoc? before the patch:

...

    TESTS:
    
    Check that argspecs of extension function/methods appear correctly,
    see >>:trac:`12849`<<:

After the patch:

...

    TESTS:
    
    Check that argspecs of extension function/methods appear correctly,
    see trac ticket #12849 <http://trac.sagemath.org/12849>:

So the docstring is longer, so some lines will end up being too long. I personally think that's okay, because of the added information.

comment:8 follow-up: Changed 8 years ago by vbraun

How about just see http://trac.sagemath.org/12849:. if you know trac you understand that thats the ticket number, and if you don't know trac then the ticket number doesn't help you any more than the url.

Also, I don't really understand why we are reimplementing sphinx here. Shouldn't we make sphinxify() spit out the correct urls instead of this bandaid? The :wikipedia: sphinx role would then also work, for example.

comment:9 in reply to: ↑ 8 Changed 8 years ago by jhpalmieri

Replying to vbraun:

How about just see http://trac.sagemath.org/12849:.

Sure, that sounds fine.

Also, I don't really understand why we are reimplementing sphinx here. Shouldn't we make sphinxify() spit out the correct urls instead of this bandaid? The :wikipedia: sphinx role would then also work, for example.

Okay, here's a better approach: turn on the "extlinks" Sphinx extension when doing introspection. Then in the notebook, docstrings look fine, but from the command line, see :trac:12849 turns into see trac ticket #12849: it includes the text, but not the associated url. So I think we should still insert the url, so I still have a version of process_trac. This version should also handle any other roles defined in extlinks.

comment:10 Changed 8 years ago by jhpalmieri

  • Keywords sd41 added

comment:11 Changed 8 years ago by vbraun

Looks good. Two tiny nit picks, can we ellipsize the precise Python version (2.7.2) since that is conflicting with #13013 already. Also, the docstring would be perfect with

- ``s`` -- string

(two minus signs before "string").

comment:12 Changed 8 years ago by jhpalmieri

Done.

Changed 8 years ago by jhpalmieri

Sage library

comment:13 Changed 8 years ago by vbraun

  • Reviewers set to Volker Braun
  • Status changed from needs_review to positive_review

Looks good!

comment:14 Changed 8 years ago by jdemeyer

  • Merged in set to sage-5.1.beta6
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.