Improve lore2sphinx buildbot results for `projects/core/howto` (except ‘tutorial/’)

[khorn]

like #4566, except for projects/core/howto (except ‘tutorial/’)

[khorn]

One thing that needs to be fixed is the "Multiple Callbacks" section of howto/defer.xhtml

[screwtape]

(In [29853]) Create branch lore2sphinx-projects-core-howto-4568

[Screwtape]

Damn, but there's a lot of files in projects/core/howto. The changes in this branch touch 33 files; the changes in #4567 touch 4. I feel sorry for whoever gets to review this ticket.

Anyway, changes on this branch include:

• Lots and lots of added trailing whitespace, to trick lore2sphinx into leaving whitespace around for Sphinx to find.
• Lots and lots of fixed links, to API docs and external websites. Sometimes I had to use my discretion to choose exactly what the link should point at.
• In the Components HOWTO, I changed "AmericanSocket" and "ForeignSocket" to be "AmericanSocket" and "UKSocket", to make it less irritatingly Americo-centric. Also, I changed "110 V" and "220 V" to "120 V" and "240 V" because Wikipedia tells me those are the nominal voltages of those respective countries (the UK claims to be 230 V ±10% like the rest of the EU, but apparently the power supply is centred on 240 V)
• Capitalisation, spelling, HTML markup inside Python listings.
• In the Deferred HOWTO, had to change some of the wording to make it legible after removing nested markup (which ReST doesn't support).
• In the glossary, replaced "NT" with "Windows" because there's no non-NT-based Windows variants any more, and because there's no product named "Windows NT" anymore.
• Also in the glossary, replaced a reference to "pyunit" with a reference to the unittest module in the standard library; I'd wager far more people reading that document will be familiar with the standard library than would be familiar with the third-party module it came from.
• In listings/pb/chatclient.py, replaced "#lookingForFourth" with "#NeedAFourth" to match the surrounding text.
• In listings/pb/chatserver.py, replaced message.find("mattress") != -1 with "mattress" in message for readability.
• In listings/pb/pb2server.py, replaced references to the variable two with self.two - otherwise, what's the point of setting self.two in the first place?
• In the Logging HOWTO:
  • Removed a link to the API docs t.p.log.msg because it doesn't actually have API docs (thanks to import-time module wizardry).
  • Added another example to startLogging highlighting that it can be used with things that aren't file handles.
  • Reworded a reference to "logging" to highlight that we're talking about the Python stdlib module.
• In the Options HOWTO, changed some Python code to avoid defining a variable then clobbering it.
• In `pb-copyable.xhtml', tried to clean up some of the mess of having a footnote containing multiple paragraphs. It renders OK at the moment, but will probably need more clean up after the Sphinx transition.
• Various shell "screenshots" used "%" as a prompt instead of "$", presumably because they were taken with csh or zsh. Changed them to "$" which I expect is more widely recognised, and to match other documents.
• Lots of other stuff.

Things not fixed:

• The page "Debugging Python(Twisted) with Emacs" includes a link to a panel from Pokey the Penguin; unfortunately Sphinx only lets you link to local images, not URLs. I'm not quite sure what to do about that.
• The usual raft of trailing spaces.

[jml]

Thanks for making this change. I can't wait to see our documentation fully moved over to Sphinx. Some thoughts on this patch:

• I'm nervous about the changes that add trailing whitespace to lines in Lore files. It will not be obvious to anyone editing these files that the whitespace is significant. Couldn't lore2sphinx be changed to make this trailing whitespace unnecessary?

• doc/core/howto/udp.xhtml seems to have bad indentation in startProtocol. The assignments to host and port need to be indented by one more space.

• The patch is inconsistent in the way it reflows long lines. Is there a reason for this?

• Many small patches would have been easier to review.

I don't see any of these (apart from the second) as being blockers to land, but I would like answers. Get back to me and I'll do a follow-up review.

[jml]

I should also mention that I only did my review based on the diff. I guess I should also look at the generated documentation for both Lore & Sphinx.

[jdb]

Adapted the lore input to fix formatting errors in the rst output

[jdb]

Improved the rst output for articles in the "Low-Level Networking and Event Loop" section of the core howto

[jdb]

Patch for the articles in the section 'Utilities' of the core howto

[jdb]

Two fixes in the row.xhtml lore input.

[jdb]

Fixes in the glossary

[jdb]

Adapted the lore input for the articles in the Perspective Broker section

[jdb]

Adapted the lore input of the articles in the "High-Level Twisted" section of the core howto

[jdb]

The attached patches fix the formatting errors in the lore2sphinx results by adapting the lore input. No modification, clarification or addition on the content is proposed.

[exarkun]

Um. How are the patches related to the branch Screwtape started?

[jdb]

Sorry, the patch applies to the trunk. I will re-post a patch on Screwtape's branch.

[jdb]

Here is a patch which improves the lore2sphinx input from the lore2sphinx-projects-core-howto-4568 branch, for the core howto, i.e. the following files :

M       doc/core/howto/components.xhtml
M       doc/core/howto/defer.xhtml
M       doc/core/howto/udp.xhtml
M       doc/core/howto/pb-intro.xhtml
M       doc/core/howto/internet-overview.xhtml
M       doc/core/howto/deferredindepth.xhtml
M       doc/core/howto/pb-copyable.xhtml
M       doc/core/howto/glossary.xhtml
M       doc/core/howto/pb-cred.xhtml
M       doc/core/howto/testing.xhtml
M       doc/core/howto/cred.xhtml
M       doc/core/howto/gendefer.xhtml
M       doc/core/howto/telnet.xhtml
M       doc/core/howto/pb-limits.xhtml
M       doc/core/howto/dirdbm.xhtml
M       doc/core/howto/pb-usage.xhtml
M       doc/core/howto/basics.xhtml
M       doc/core/howto/row.xhtml
M       doc/core/howto/design.xhtml
M       doc/core/howto/process.xhtml
M       doc/core/howto/quotes.xhtml
M       doc/core/howto/upgrading.xhtml

This patch makes the previous patches attached on this ticket obsolete.

[thijs]

At some point you change 'expansive' into 'expensive' but I think 'expansive' as in large, was actually the right word there?

<p>The docstring is quite expensive (see <code class="API">twisted.cred.portal</code>), but in 

[jdb]

Yes. I thought this was an error like seperate/separate. The new patch fixes this.

[glyph]

Tickets should be unassigned for review, unless they need to be reviewed by a particular person.

[exarkun]

(In [30657]) Apply core-howto2.xhtml.patch

refs #4568

[exarkun]

(In [30659]) Merge the pb parts of the impossibly huge #4568 branch

refs #4568 refs #4863

[exarkun]

(In [30661]) Merge the logging parts of the impossibly huge #4568 branch

refs #4568 refs #4864

[exarkun]

(In [30663]) Merge the quotes parts of the impossibly huge #4568 branch

refs #4865 refs #4568

[exarkun]

(In [30665]) Merge the meta-ish doc-y parts of the impossibly huge #4568 branch

refs #4866 refs #4568

[exarkun]

(In [30667]) Merge the components parts of the impossibly huge #4568 branch

refs #4568 refs #4867

[exarkun]

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

refs #4868 refs #4568

[exarkun]

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

refs #4568 refs #4869

[exarkun]

(In [30673]) Merge the process parts of the impossibly huge #4568 branch

refs #4870 refs #4568

[exarkun]

(In [30675]) Merge the database parts of the impossibly huge #4568 branch

refs #4871 refs #4568

[exarkun]

(In [30677]) Merge the cred parts of the impossibly huge #4568 branch

refs #4568 refs #4872

[exarkun]

(In [30679]) Merge the basics and application parts of the impossibly huge #4568 branch

refs #4568 refs #4873

[exarkun]

(In [30681]) Merge the telnet parts of the impossibly huge #4568 branch

refs #4874 refs #4568

[exarkun]

(In [30683]) Merge the plugin parts of the impossibly huge #4568 branch

refs #4568 refs #4875

[exarkun]

(In [30685]) Merge the options parts of the impossibly huge #4568 branch

refs #4568 refs #4876

[exarkun]

(In [30688]) Merge the telnet parts of the impossibly huge #4568 branch

refs #4568 refs #4877

[exarkun]

(In [30690]) Merge the producers parts of the impossibly huge #4568 branch

refs #4568 refs #4878

[exarkun]

(In [30692]) Merge the dirdbm parts of the impossibly huge #4568 branch

refs #4568 refs #4879

[exarkun]

This ticket picked apart into the above linked smaller tickets, with individually easier to review changesets.