Opened 4 years ago

Closed 3 years ago

#21592 closed defect (fixed)

".. note:" must be ".. note::"

Reported by: jmantysalo Owned by:
Priority: major Milestone: sage-7.6
Component: documentation Keywords:
Cc: chapoton, jhpalmieri Merged in:
Authors: Jori Mäntysalo, John Palmieri, Frédéric Chapoton Reviewers: John Palmieri, Jori Mäntysalo, Frédéric Chapoton
Report Upstream: N/A Work issues:
Branch: 4cc0af9 (Commits) Commit: 4cc0af934453b67bcc59cc2fd42e5d04b8354558
Dependencies: Stopgaps:

Description (last modified by jmantysalo)

See for example isogeny_graph() on elliptic curves over the rational numbers: http://sage-doc.sis.uta.fi/reference/curves/sage/schemes/elliptic_curves/ell_rational_field.html. The note "The vertices are labeled 1 to n - -" is not shown at all. The reason is

.. note:

that should be

.. note::

According to

egrep -R -i '^ +\.\. note:$' src/sage

there are 19 files with this bug and a total of 34 lines to correct.

(Also this patch corrects some "Dieudonne" to "Dieudonné".)

Change History (26)

comment:1 Changed 4 years ago by jmantysalo

  • Component changed from PLEASE CHANGE to documentation
  • Type changed from PLEASE CHANGE to defect

comment:2 Changed 4 years ago by jmantysalo

  • Branch set to u/jmantysalo/note-colons

comment:3 Changed 4 years ago by jmantysalo

  • Authors set to Jori Mäntysalo
  • Cc chapoton added
  • Commit set to 7dedbb75030d8c083cbb1b7eeef4abbda94366af

Perl is... perl.

find src/sage -name '*.py' -or -name '*.pyx' -or -name '*.pxi' | xargs perl -e 's|(^ +)\.\. note:(?=$)|$1.. note::|g;' -p -i.bak

Anyways, this should work. Not tested yet, just compiling.


New commits:

7dedbb7Second colon for .. note: -lines.

comment:4 Changed 4 years ago by jmantysalo

  • Cc jhpalmieri added

John, maybe you are also interested in this. Does this make some harm to the code removing TESTS-blocks?

comment:5 follow-up: Changed 4 years ago by jhpalmieri

Why not use Sage for the search?

sage: search_src('\.\. note:[^:]')

comment:6 in reply to: ↑ 5 Changed 4 years ago by jmantysalo

Replying to jhpalmieri:

Why not use Sage for the search?

sage: search_src('\.\. note:[^:]')

Just that I didn't remember that. Thanks!

Next question: what to do for blocks that have

.. note:

Not indented block here.

? Or how to found them automatically?

Uh, I don't like Sphinx.

comment:7 Changed 4 years ago by git

  • Commit changed from 7dedbb75030d8c083cbb1b7eeef4abbda94366af to 2ac0b3460608b4130f88801b507eb6d518f63e43

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

2ac0b34Indentation.

comment:8 follow-up: Changed 4 years ago by jhpalmieri

To find such blocks:

sage: search_src(r'([ ]*)\.\. note::[ ]*\n\n\1[^ ]', multiline=True)
categories/map.pyx
interfaces/r.py
rings/polynomial/pbori.pyx

With the multiline=True option, it doesn't return the line number, just the file. But it's not hard to find the offending lines. map.pyx:

  • src/sage/categories/map.pyx

    diff --git a/src/sage/categories/map.pyx b/src/sage/categories/map.pyx
    index 5fd7637..8c36b47 100644
    a b cdef class Map(Element): 
    510510
    511511        .. NOTE::
    512512
    513         By default, the empty string is returned. Subclasses may overload this method.
     513            By default, the empty string is returned. Subclasses may overload this method.
    514514
    515515        EXAMPLE::
    516516

r.py:

  • src/sage/interfaces/r.py

    diff --git a/src/sage/interfaces/r.py b/src/sage/interfaces/r.py
    index f8eda3b..8875b50 100644
    a b class R(ExtraTabCompletion, Expect): 
    787787
    788788            .. note::
    789789
    790             This is similar to typing r.command?.
     790                This is similar to typing r.command?.
    791791        """
    792792        s = self.eval('help("%s")'%command).strip()     # ?cmd is only an unsafe shortcut
    793793        import sage.plot.plot

The last one, pbori.pyx, is a false positive, probably because of a mistake in my regular expression: it matches because of blocks with more than one blank line between .. note:: and the indented block.

comment:9 Changed 4 years ago by git

  • Commit changed from 2ac0b3460608b4130f88801b507eb6d518f63e43 to e4bde004ed722b69f65ca333453bc103ee92d0ce

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

e4bde00More indentation.

comment:10 Changed 4 years ago by git

  • Commit changed from e4bde004ed722b69f65ca333453bc103ee92d0ce to 8d4dda9e423934e6a9ac9206f9243b59a529f397

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

8d4dda9Still more indentation.

comment:11 in reply to: ↑ 8 Changed 4 years ago by jmantysalo

  • Status changed from new to needs_review

Replying to jhpalmieri:

To find such blocks:

sage: search_src(r'([ ]*)\.\. note::[ ]*\n\n\1[^ ]', multiline=True)
categories/map.pyx
interfaces/r.py
rings/polynomial/pbori.pyx

Thanks.

Now this one should work, at last. Sphinx seems to be very, very bad and error-prone for documentation like this. It would need much more structure and error checking.

comment:12 Changed 4 years ago by jhpalmieri

  • Branch changed from u/jmantysalo/note-colons to u/jhpalmieri/note-colons

comment:13 Changed 4 years ago by jhpalmieri

  • Commit changed from 8d4dda9e423934e6a9ac9206f9243b59a529f397 to 19d2444318c0225744d66c89cfe2a9956357247b

I found a few more. I think that Sphinx treats any line that starts with .. text as a comment unless it is of the form .. directive::. In particular, lines like .. note: blah are ignored completely by Sphinx, so I fixed those.


New commits:

19d2444Fix a few more ".. note::" blocks.

comment:14 follow-up: Changed 4 years ago by jhpalmieri

  • Reviewers set to John Palmieri

I'm happy with your original version, so if you're okay with my changes, feel free to set a positive review.

comment:15 in reply to: ↑ 14 Changed 4 years ago by jmantysalo

  • Status changed from needs_review to needs_work

Replying to jhpalmieri:

I'm happy with your original version, so if you're okay with my changes, feel free to set a positive review.

Can you re-check this? It seems that elliptic_curves/padic_lseries.html contains no NOTE-blocks, but btquotients/btquotient.html is fine. I don't see why so.

comment:16 Changed 4 years ago by jmantysalo

  • Authors changed from Jori Mäntysalo to Jori Mäntysalo, John Palmieri
  • Reviewers changed from John Palmieri to John Palmieri, Jori Mäntysalo

comment:17 follow-up: Changed 4 years ago by jhpalmieri

The methods in padic_lseries.py which contain the .. notes: blocks start with an underscore, so they don't appear in the documentation. I think we should still fix the formatting.

comment:18 in reply to: ↑ 17 Changed 4 years ago by jmantysalo

  • Status changed from needs_work to positive_review

Replying to jhpalmieri:

The methods in padic_lseries.py which contain the .. notes: blocks start with an underscore

Duh.

comment:19 Changed 4 years ago by vbraun

  • Status changed from positive_review to needs_work

Merge conflict

comment:20 follow-up: Changed 4 years ago by tscrim

The way prescribed by the dev guide it .. NOTE::. So while you're at it, could you make that change as well?

comment:21 in reply to: ↑ 20 Changed 4 years ago by jmantysalo

Replying to tscrim:

The way prescribed by the dev guide it .. NOTE::. So while you're at it, could you make that change as well?

It is easier to do this first, and then later change all with a perl command, just like in #21648. (Btw, thanks for that.)

comment:22 Changed 3 years ago by chapoton

  • Branch changed from u/jhpalmieri/note-colons to public/21592
  • Commit changed from 19d2444318c0225744d66c89cfe2a9956357247b to f41bf09d6bf32e59810d654f074c73c70a480570
  • Status changed from needs_work to needs_review

rebased on 7.6.b4


New commits:

f41bf09Merge branch 'u/jhpalmieri/note-colons' in 7.6.b4

comment:23 Changed 3 years ago by git

  • Commit changed from f41bf09d6bf32e59810d654f074c73c70a480570 to 4cc0af934453b67bcc59cc2fd42e5d04b8354558

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

4cc0af9trac 21592 some missing accents

comment:24 Changed 3 years ago by chapoton

  • Reviewers changed from John Palmieri, Jori Mäntysalo to John Palmieri, Jori Mäntysalo, Frédéric Chapoton

ok, looks good to me. I made one more commit about some missing accents in one of the touched files.

If you agree with my changes, you can set to positive.

comment:25 Changed 3 years ago by jmantysalo

  • Authors changed from Jori Mäntysalo, John Palmieri to Jori Mäntysalo, John Palmieri, Frédéric Chapoton
  • Description modified (diff)
  • Milestone changed from sage-7.4 to sage-7.6
  • Status changed from needs_review to positive_review

LGTM. I changed some metadata.

comment:26 Changed 3 years ago by vbraun

  • Branch changed from public/21592 to 4cc0af934453b67bcc59cc2fd42e5d04b8354558
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.