Improve lore2sphinx buildbot results for deferred documents in `projects/core/howto/`

[exarkun]

like #4566, except for these documents:

• defer
• gendefer
• deferredindepth

[exarkun]

(In [30668]) Branching to 'defer-sphinx-4868'

[exarkun]

(In [30669]) Merge the deferred parts of the impossibly huge #4568 branch

refs #4868 refs #4568

[jerub]

Using python-docutils 0.6-5 from ubuntu and lore2sphinx from  https://bitbucket.org/khorn/lore2sphinx I get errors such as:

defer.rst:145: (INFO/1) No directive entry for "code-block" in module "docutils.parsers.rst.languages.en".
Trying "code-block" as canonical directive name.
defer.rst:145: (ERROR/3) Unknown directive type "code-block".

and

/var/tmp/doc/core/howto/defer.rst:773: (INFO/1) No role entry for "ref" in module "docutils.parsers.rst.languages.en".
Trying "ref" as canonical role name.
/var/tmp/doc/core/howto/defer.rst:773: (ERROR/3) Unknown interpreted text role "ref".
/var/tmp/doc/core/howto/defer.rst:919: (INFO/1) No role entry for "doc" in module "docutils.parsers.rst.languages.en".
Trying "doc" as canonical role name.
/var/tmp/doc/core/howto/defer.rst:919: (ERROR/3) Unknown interpreted text role "doc".
/var/tmp/doc/core/howto/defer.rst:45: (INFO/1) Hyperlink target "core-howto-defer-deferreds" is not referenced.
/var/tmp/doc/core/howto/defer.rst:750: (INFO/1) Hyperlink target "core-howto-defer-class" is not referenced.

Please give a suitable procedure for testing these documents.

This is my lore2sphinx.conf:

[general]
default_profile = twisted

[twisted]
lore_dir = /home/sthorne/src/svnTwisted/trunk/doc/
output_dir = /var/tmp/doc

The above error message was one of many emitted when I attempted:

rst2html --verbose /var/tmp/doc/core/howto/defer.rst > /dev/null

Please provide a reproducable procedure for using lore2sphinx and I can review.

[jerub]

exarkun has given me a combination of urls  http://buildbot.twistedmatrix.com/builders/sphinx-documentation and  http://buildbot.twistedmatrix.com/builds/sphinx-html/ which allow me to see generated docs. Here are some editing notes:

 http://buildbot.twistedmatrix.com/builds/sphinx-html/sphinx-html-15745/projects/core/howto/defer.html

Each of these sections are referred to by their anchor tag, but I cannot link to them due to the trac limit on number of external links per comment to reduce spam.

#deferreds there are several typographical errors, anything bolded has a space after it and it should not have. i.e. callbacks , or a callback chain ),.

#errbacks has extra spaces in each of the last four paragraphs.

#handling-either-synchronous-or-asynchronous-results last paragraph has extra spaces after words.

It seems the entire document has a large number of these errors. Is there a way to fix them or is this a limitation of sphinx/lore/etc? Punctuation after styling, regardless of bold, italic or monospace seems to suffer this.

[khorn]

space + punctuation errors in generated docs are not easily fixable in the automated conversion process.

This one can be merged.

[khorn]

(In [31104]) Merge defer-sphinx-4868

Author: Screwtape Reviewers: tenth Fixes: #4868

Improve buildbot results for defer docs in lore to sphinx conversion.