Opened 4 years ago

Closed 4 years ago

#4572 enhancement closed fixed (fixed)

Improve lore2sphinx buildbot results for `projects/mail`

Reported by: khorn Owned by:
Priority: normal Milestone: Lore to Sphinx
Component: mail Keywords:
Cc: jeandaniel.browne@… Branch: branches/lore2sphinx-mail-4572
(diff, github, buildbot, log)
Author: jdb Launchpad Bug:

Description

like #4566, except for projects/mail

Attachments (5)

index.rst (436 bytes) - added by jdb 4 years ago.
index.2.rst (526 bytes) - added by jdb 4 years ago.
mail/examples/index.rst
smtpclient.rst (28.9 KB) - added by jdb 4 years ago.
Corrected verison of the SMTP tutorial
smtpclient-old.rst (29.3 KB) - added by jdb 4 years ago.
Open version of the SMTP tutorial
smtpclient.xhtml.patch (17.0 KB) - added by jdb 4 years ago.

Download all attachments as: .zip

Change History (18)

comment:1 Changed 4 years ago by khorn

  • Milestone set to Lore to Sphinx

Changed 4 years ago by jdb

Changed 4 years ago by jdb

mail/examples/index.rst

Changed 4 years ago by jdb

Corrected verison of the SMTP tutorial

Changed 4 years ago by jdb

Open version of the SMTP tutorial

comment:2 Changed 4 years ago by jdb

  • Cc jeandaniel.browne@… added
The mail documentation chunk is composed of three rst files: two
short listings and one sizeable tutorial::

  doc/projects/mail
  |-- examples
  |   `-- index.rst
  |-- index.rst
  `-- tutorial
      `-- smtpclient
          `-- smtpclient.rst

The transformation is almost correct, there are two bugs that show in HTML (they show especially in the file mail/tutorial/smtpclient/smtpclient.rst):

#. there is a space missing a space before an italic or preformatted
   markup (not always reproduceable). This bug is a problem as it 
   disables the markup.

   ex: look for the text : "use by``twistd`` ." The original xhtml was
   "use by <code>twistd</code>.</p>". Because of the missing space, the
   markup is incorrect and the four backquotes can be read untransformed
   in html.

#. there is always extra space in the middle of:

   - an underline or preformatted string, or a link: ("\:ref:\`link` ,")

   - a dot, comma, parenthesis, colon, apostrophy

   ex: look for the text : "\*application service\* ."

Often both bugs happen on the same chunk of text. Here are two other minor bugs of the rst file which do not show in HTML: 

- four or even six unneeded blank lines between text blocks while 
  one was enough 

- weird paragraph *fill* (lines sometimes 30 characters long, sometimes 150)

Attached are the three rst files corrected by hand. Also the version buggy version of the tutorial is attached. 

Question: is there a repository of restructured text that I can commit the version corrected by hand?

comment:3 follow-up: Changed 4 years ago by exarkun

Apparently #4566 didn't explain that the idea here is not to hand-fix the rst output, but to fix the Lore input so that the output comes out looking better.

Changed 4 years ago by jdb

comment:4 in reply to: ↑ 3 ; follow-up: Changed 4 years ago by jdb

Replying to exarkun:

Apparently #4566 didn't explain that the idea here is not to hand-fix the rst output, but to fix the Lore input so that the output comes out looking better.

Attached is a patch to the smtpclient xhtml/lore input where no text markup follows a newline character. This seems to fix the problem of rst markup being visible in HTML because of a missing space in the rst file.

Concerning the problem of the extra space created between a markup and a final dot, I haven't found a way yet to "adapt" the xhtml.

Does someone have trick for getting rid of the extra space?

It is also possible to rephrase each sentence so that no markuped expressions is in the end of a sentence (we do not want to do this I guess). It is also possible to leave this minor bug unfixed and fix it later on in the rst source.

comment:5 Changed 4 years ago by thijs

  • Component changed from core to mail
  • Keywords review added
  • Owner glyph deleted

Putting the patch up for review.

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

Replying to jdb:

Concerning the problem of the extra space created between a markup and a final dot, I haven't found a way yet to "adapt" the xhtml.

Yeah, I believe the plan is to fix the generated ReST markup after we throw the switch and make the Sphinx docs the official ones.

comment:7 Changed 4 years ago by khorn

Yes, that is indeed the plan. Once this set of tickets has been completed, we'll convert to Sphinx and then clean up the remaining issues with another set of tickets. There are some issues which are just very difficult to translate automatically (as jdb has discovered).

comment:8 Changed 4 years ago by exarkun

  • Author set to exarkun
  • Branch set to branches/lore2sphinx-mail-4572

(In [29968]) Branching to 'lore2sphinx-mail-4572'

comment:9 Changed 4 years ago by exarkun

(In [29969]) Apply smtpclient.xhtml.patch

refs #4572

comment:10 Changed 4 years ago by exarkun

(In [29970]) Correct two more whitespace issues which cause lore2sphinx to emit bogus restructured text

refs #4572

comment:11 Changed 4 years ago by exarkun

  • Author changed from exarkun to jdb
  • Keywords review removed
  • Owner set to exarkun

Thanks. This looks good, except for a couple extra changes I made above. Merging.

comment:12 Changed 4 years ago by exarkun

  • Resolution set to fixed
  • Status changed from new to closed

(In [29972]) Merge lore2sphinx-mail-4572

Author: jdb
Reviewer: exarkun
Fixes: #4572

Various changes to the Twisted Mail documentation to improve the results
of the lore2sphinx tool.

comment:13 Changed 4 years ago by <automation>

  • Owner exarkun deleted
Note: See TracTickets for help on using tickets.