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)
Change History (15)
comment:1 Changed 8 years ago by
- Cc kcrisman added
comment:2 Changed 8 years ago by
- Cc jhpalmieri added
comment:3 Changed 8 years ago by
comment:4 Changed 8 years ago by
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
- 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
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
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: ↓ 9 Changed 8 years ago by
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
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
- Keywords sd41 added
comment:11 Changed 8 years ago by
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
Done.
comment:13 Changed 8 years ago by
- Reviewers set to Volker Braun
- Status changed from needs_review to positive_review
Looks good!
comment:14 Changed 8 years ago by
- Merged in set to sage-5.1.beta6
- Resolution set to fixed
- Status changed from positive_review to closed
Does this even work in the notebook? It doesn't for me: I only see it working successfully in the reference manual.