Opened 5 years ago

Closed 6 months ago

#19972 closed enhancement (worksforme)

Fix doc syntax highlighting

Reported by: jdemeyer Owned by:
Priority: major Milestone: sage-duplicate/invalid/wontfix
Component: packages: standard Keywords:
Cc: slelievre Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: #19968 Stopgaps:

Status badges

Description

Currently, the ....: doctest continuation lines are not parsed correctly by Pygments. As a consequence, those lines are not syntax highlighted.

We should also investigate if we can extend Pygments without patching it and whether the highlighting for Sage can be pushed upstream.

Change History (6)

comment:1 Changed 6 months ago by jhpalmieri

  • Cc slelievre added

I think this has been solved. src/sage/docs/conf.py has the lines

# Default lexer to use when highlighting code blocks, using the IPython
# console lexers. 'ipycon' is the IPython console, which is what we want
# for most code blocks: anything with "sage:" prompts. For other IPython,
# like blocks which might appear in a notebook cell, use 'ipython'.
highlighting.lexers['ipycon'] = IPythonConsoleLexer(in1_regex=r'sage: ', in2_regex=r'[.][.][.][.]: ')
highlighting.lexers['ipython'] = IPyLexer()
highlight_language = 'ipycon'

and in particular, in2_regex defines ....: as syntax for an input prompt. The documentation looks okay to me: here for example.

comment:2 Changed 6 months ago by jhpalmieri

  • Milestone changed from sage-7.1 to sage-duplicate/invalid/wontfix
  • Status changed from new to needs_review

I propose closing as a duplicate of #27528.

comment:3 Changed 6 months ago by chapoton

how can I check that this works ?

comment:4 Changed 6 months ago by jhpalmieri

I posted a link to part of Sage's documentation in comment:1, in which the docstrings starting with "....:" are highlighted correctly (as far as I can tell). You can also search for "....:" in Sage sources, and then look in your local copy of the reference manual to see if those lines are highlighted. You could also make the change

  • src/sage/docs/conf.py

    diff --git a/src/sage/docs/conf.py b/src/sage/docs/conf.py
    index bf2024ce5b..502289b0dd 100644
    a b pygments_style = 'sphinx' 
    156156# console lexers. 'ipycon' is the IPython console, which is what we want
    157157# for most code blocks: anything with "sage:" prompts. For other IPython,
    158158# like blocks which might appear in a notebook cell, use 'ipython'.
    159 highlighting.lexers['ipycon'] = IPythonConsoleLexer(in1_regex=r'sage: ', in2_regex=r'[.][.][.][.]: ')
     159highlighting.lexers['ipycon'] = IPythonConsoleLexer()
    160160highlighting.lexers['ipython'] = IPyLexer()
    161161highlight_language = 'ipycon'
    162162

and rebuild Sage and its reference manual (make doc-clean then make) to see what effect that line has. I did this, and the highlighting on lines starting either "sage:" or "....:" disappears.

comment:5 Changed 6 months ago by jhpalmieri

More evidence: if you look at the html source, with the highlighting code in place, "sage:" and "....:" are labeled as, for example:

<span class="gp">....: </span>

and looking at the file basic.css, "gp" stands for "generic prompt". Without the highlighting code (that is, if you make the change in the previous comment), the whole line instead is marked class="go", and "go" stands for "generic output".

I suppose we could write a doctest for this, but I don't have the energy right now.

comment:6 Changed 6 months ago by chapoton

  • Resolution set to worksforme
  • Status changed from needs_review to closed

ok, thanks. Look good to me.

Note: See TracTickets for help on using tickets.