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:

GitHub link to the corresponding issue

Description (last modified by jdemeyer)

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 in reply to:  description Changed 7 years ago by dkrenn

Replying to klee:

We need a new magic comment

# optional - latex

for doctests that require latex installed on the system.

In addition, 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.

Maybe also adding a link to the corresponding part of the Python manual.

The two issues should be split on two tickets.

comment:2 Changed 7 years ago by jdemeyer

Component: doctest frameworkdocumentation
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 jhpalmieri

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 jhpalmieri

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): 
    259259                        if versions[0] == versions[1]:
    260260                            options.optional.add(pkg)
    261261
     262                from sage.misc.latex import have_latex
     263                if have_latex():
     264                    options.optional.add('latex')
     265
    262266                # Check that all tags are valid
    263267                for o in options.optional:
    264268                    if not optionaltag_regex.search(o):

comment:5 Changed 7 years ago by jdemeyer

See #13540 and #18904 for general discussions about automatically detecting optional flags.

comment:6 Changed 7 years ago by jhpalmieri

And now #20182, apparently.

comment:7 Changed 7 years ago by klee

Wow, you are so fast! Thank you.

comment:8 Changed 7 years ago by klee

Branch: public/20176
Commit: b4456b1047adff22bd4e5b6c56425933f89e3894

New commits:

9477209Remark on the ellipsis marker
b4456b1Corrected the link to Python's manual

comment:9 Changed 7 years ago by klee

Authors: Kwankyu Lee
Status: newneeds_review

comment:10 Changed 7 years ago by dkrenn

Reviewers: Daniel Krenn
Status: needs_reviewneeds_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 git

Commit: b4456b1047adff22bd4e5b6c56425933f89e389457bfdee4eec37a346ed6d05d262c919087f8d3da

Branch pushed to git repo; I updated commit sha1. New commits:

57bfdeeImprove python-link

comment:12 in reply to:  10 Changed 7 years ago by klee

Replying to dkrenn:

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?

Nice tips. Thank you!

comment:13 Changed 7 years ago by klee

Status: needs_workneeds_review

comment:14 Changed 7 years ago by dkrenn

Status: needs_reviewneeds_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 git

Commit: 57bfdee4eec37a346ed6d05d262c919087f8d3da5694f4ee95ce733d7b30619f23fcd17177194207

Branch pushed to git repo; I updated commit sha1. New commits:

5694f4eSplit long lines

comment:16 Changed 7 years ago by klee

Milestone: sage-7.1sage-7.2

comment:17 Changed 7 years ago by klee

Status: needs_workneeds_review

comment:18 Changed 7 years ago by dkrenn

Status: needs_reviewpositive_review

Looks good now.

comment:19 Changed 7 years ago by vbraun

Branch: public/201765694f4ee95ce733d7b30619f23fcd17177194207
Resolution: fixed
Status: positive_reviewclosed
Note: See TracTickets for help on using tickets.