Document ellipsis in doctests

[klee]

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.

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

[jdemeyer]

You can already use # optional - latex right now.

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

[jhpalmieri]

For the record, I'm thinking of something like

src/sage/doctest/control.py

@@ -259 +259 @@
                         if versions[0] == versions[1]:
                             options.optional.add(pkg)
 
+                from sage.misc.latex import have_latex
+                if have_latex():
+                    options.optional.add('latex')
+
                 # Check that all tags are valid
                 for o in options.optional:
                     if not optionaltag_regex.search(o):

[jdemeyer]

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

[jhpalmieri]

And now #20182, apparently.

[klee]

Wow, you are so fast! Thank you.

[klee]

New commits:

​9477209	Remark on the ellipsis marker
​b4456b1	Corrected the link to Python's manual

[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?

[git]

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

​57bfdee

Improve python-link

[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!

[dkrenn]

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.

[git]

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

​5694f4e

Split long lines

[dkrenn]

Looks good now.