Opened 7 years ago
Closed 7 years ago
#20176 closed enhancement (fixed)
Document ellipsis in doctests
Reported by: | klee | Owned by: | |
---|---|---|---|
Priority: | minor | Milestone: | sage-7.2 |
Component: | documentation | Keywords: | |
Cc: | Merged in: | ||
Authors: | Kwankyu Lee | Reviewers: | Daniel Krenn |
Report Upstream: | N/A | Work issues: | |
Branch: | 5694f4e (Commits, GitHub, GitLab) | Commit: | 5694f4ee95ce733d7b30619f23fcd17177194207 |
Dependencies: | Stopgaps: |
Description (last modified by )
The developer's manual needs to be updated to include an explanation of the ellipsis in doctests. For your information: The ellipsis is part of Python's doctest framework. In Python it's not enabled by default, but in Sage it is.
Change History (19)
comment:1 Changed 7 years ago by
comment:2 Changed 7 years ago by
Component: | doctest framework → documentation |
---|---|
Description: | modified (diff) |
Summary: | New magic comment for doctest "# optional - latex" → Document ellipsis in doctests |
You can already use # optional - latex
right now.
comment:3 Changed 7 years ago by
Regarding latex
, we could consider trying to detect whether the system has LaTeX installed and so whether to run those doctests automatically. I don't want to do this for every non-Sage piece of software mentioned in an optional flag, but maybe LaTeX deserves a special case? I'm not sure.
comment:4 Changed 7 years ago by
For the record, I'm thinking of something like
-
src/sage/doctest/control.py
diff --git a/src/sage/doctest/control.py b/src/sage/doctest/control.py index 6a49e68..79567db 100644
a b class DocTestController(SageObject): 259 259 if versions[0] == versions[1]: 260 260 options.optional.add(pkg) 261 261 262 from sage.misc.latex import have_latex 263 if have_latex(): 264 options.optional.add('latex') 265 262 266 # Check that all tags are valid 263 267 for o in options.optional: 264 268 if not optionaltag_regex.search(o):
comment:5 Changed 7 years ago by
comment:8 Changed 7 years ago by
Branch: | → public/20176 |
---|---|
Commit: | → b4456b1047adff22bd4e5b6c56425933f89e3894 |
comment:9 Changed 7 years ago by
Authors: | → Kwankyu Lee |
---|---|
Status: | new → needs_review |
comment:10 follow-up: 12 Changed 7 years ago by
Reviewers: | → Daniel Krenn |
---|---|
Status: | needs_review → needs_work |
Something like :python:`RuntimeError<library/exceptions.html#exceptions.RuntimeError>`
should work for Python-links.
Changing ellipsis marker (...)
to ellipsis marker ``...``
would (IMHO) make it clearer what the actual marker is, since it is typeset as code (tt-font). What do you think?
comment:11 Changed 7 years ago by
Commit: | b4456b1047adff22bd4e5b6c56425933f89e3894 → 57bfdee4eec37a346ed6d05d262c919087f8d3da |
---|
Branch pushed to git repo; I updated commit sha1. New commits:
57bfdee | Improve python-link
|
comment:12 Changed 7 years ago by
Replying to dkrenn:
Something like
:python:`RuntimeError<library/exceptions.html#exceptions.RuntimeError>`
should work for Python-links.Changing
ellipsis marker (...)
toellipsis marker ``...``
would (IMHO) make it clearer what the actual marker is, since it is typeset as code (tt-font). What do you think?
Nice tips. Thank you!
comment:13 Changed 7 years ago by
Status: | needs_work → needs_review |
---|
comment:14 Changed 7 years ago by
Status: | needs_review → needs_work |
---|
Thanks for changing. One very small issue I just saw now: Could you make two line-breaks to avoid the long lines? (PEP8) Apart from this, positive_review.
comment:15 Changed 7 years ago by
Commit: | 57bfdee4eec37a346ed6d05d262c919087f8d3da → 5694f4ee95ce733d7b30619f23fcd17177194207 |
---|
Branch pushed to git repo; I updated commit sha1. New commits:
5694f4e | Split long lines
|
comment:16 Changed 7 years ago by
Milestone: | sage-7.1 → sage-7.2 |
---|
comment:17 Changed 7 years ago by
Status: | needs_work → needs_review |
---|
comment:19 Changed 7 years ago by
Branch: | public/20176 → 5694f4ee95ce733d7b30619f23fcd17177194207 |
---|---|
Resolution: | → fixed |
Status: | positive_review → closed |
Replying to klee:
Maybe also adding a link to the corresponding part of the Python manual.
The two issues should be split on two tickets.