Opened 4 years ago
Closed 3 years ago
#21592 closed defect (fixed)
".. note:" must be ".. note::"
Reported by:  jmantysalo  Owned by:  

Priority:  major  Milestone:  sage7.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 )
See for example isogeny_graph()
on elliptic curves over the rational numbers: http://sagedoc.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
 Component changed from PLEASE CHANGE to documentation
 Type changed from PLEASE CHANGE to defect
comment:2 Changed 4 years ago by
 Branch set to u/jmantysalo/notecolons
comment:3 Changed 4 years ago by
 Cc chapoton added
 Commit set to 7dedbb75030d8c083cbb1b7eeef4abbda94366af
comment:4 Changed 4 years ago by
 Cc jhpalmieri added
John, maybe you are also interested in this. Does this make some harm to the code removing TESTS
blocks?
comment:5 followup: ↓ 6 Changed 4 years ago by
Why not use Sage for the search?
sage: search_src('\.\. note:[^:]')
comment:6 in reply to: ↑ 5 Changed 4 years ago by
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
 Commit changed from 7dedbb75030d8c083cbb1b7eeef4abbda94366af to 2ac0b3460608b4130f88801b507eb6d518f63e43
Branch pushed to git repo; I updated commit sha1. New commits:
2ac0b34  Indentation.

comment:8 followup: ↓ 11 Changed 4 years ago by
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): 510 510 511 511 .. NOTE:: 512 512 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. 514 514 515 515 EXAMPLE:: 516 516
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): 787 787 788 788 .. note:: 789 789 790 This is similar to typing r.command?.790 This is similar to typing r.command?. 791 791 """ 792 792 s = self.eval('help("%s")'%command).strip() # ?cmd is only an unsafe shortcut 793 793 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
 Commit changed from 2ac0b3460608b4130f88801b507eb6d518f63e43 to e4bde004ed722b69f65ca333453bc103ee92d0ce
Branch pushed to git repo; I updated commit sha1. New commits:
e4bde00  More indentation.

comment:10 Changed 4 years ago by
 Commit changed from e4bde004ed722b69f65ca333453bc103ee92d0ce to 8d4dda9e423934e6a9ac9206f9243b59a529f397
Branch pushed to git repo; I updated commit sha1. New commits:
8d4dda9  Still more indentation.

comment:11 in reply to: ↑ 8 Changed 4 years ago by
 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 errorprone for documentation like this. It would need much more structure and error checking.
comment:12 Changed 4 years ago by
 Branch changed from u/jmantysalo/notecolons to u/jhpalmieri/notecolons
comment:13 Changed 4 years ago by
 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:
19d2444  Fix a few more ".. note::" blocks.

comment:14 followup: ↓ 15 Changed 4 years ago by
 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
 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 recheck 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
 Reviewers changed from John Palmieri to John Palmieri, Jori Mäntysalo
comment:17 followup: ↓ 18 Changed 4 years ago by
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
 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:20 followup: ↓ 21 Changed 4 years ago by
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
comment:22 Changed 3 years ago by
 Branch changed from u/jhpalmieri/notecolons to public/21592
 Commit changed from 19d2444318c0225744d66c89cfe2a9956357247b to f41bf09d6bf32e59810d654f074c73c70a480570
 Status changed from needs_work to needs_review
comment:23 Changed 3 years ago by
 Commit changed from f41bf09d6bf32e59810d654f074c73c70a480570 to 4cc0af934453b67bcc59cc2fd42e5d04b8354558
Branch pushed to git repo; I updated commit sha1. New commits:
4cc0af9  trac 21592 some missing accents

comment:24 Changed 3 years ago by
 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
 Description modified (diff)
 Milestone changed from sage7.4 to sage7.6
 Status changed from needs_review to positive_review
LGTM. I changed some metadata.
comment:26 Changed 3 years ago by
 Branch changed from public/21592 to 4cc0af934453b67bcc59cc2fd42e5d04b8354558
 Resolution set to fixed
 Status changed from positive_review to closed
Perl is... perl.
Anyways, this should work. Not tested yet, just compiling.
New commits:
Second colon for .. note: lines.