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

[vbraun]

#12490 introduced a :trac:12490 role to sphinx, which is typeset into "trac ticket #". 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.

CC: @hivert @kcrisman @jhpalmieri

Component: documentation

Keywords: sd41

Author: John Palmieri

Reviewer: Volker Braun

Merged: sage-5.1.beta6

Issue created by migration from https://trac.sagemath.org/ticket/13116

[jhpalmieri]

comment:3

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

[vbraun]

comment:4

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.

[jhpalmieri]

Author: John Palmieri

[jhpalmieri]

comment:5

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

[kcrisman]

comment:6

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?

[jhpalmieri]

comment:7

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.

[vbraun]

comment:8

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.

[jhpalmieri]

comment:9

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`.

[jhpalmieri]

Changed keywords from none to sd41

[vbraun]

comment:11

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").

[jhpalmieri]

comment:12

Done.

[jhpalmieri]

Sage library

[vbraun]

Reviewer: Volker Braun

[vbraun]

comment:13

Attachment: trac_13116-trac-docstring.patch.gz

Looks good!

[jdemeyer]

Merged: sage-5.1.beta6