Opened 4 years ago

Closed 3 years ago

#4568 enhancement closed duplicate (duplicate)

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

Reported by: khorn Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: Branch: branches/lore2sphinx-projects-core-howto-4568
(diff, github, buildbot, log)
Author: screwtape Launchpad Bug:

Description

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

Attachments (9)

core-introduction-tutorial.xhtml.patch (5.3 KB) - added by jdb 4 years ago.
Adapted the lore input to fix formatting errors in the rst output
core-lowlevel.xhtml.patch (17.1 KB) - added by jdb 4 years ago.
Improved the rst output for articles in the "Low-Level Networking and Event Loop" section of the core howto
utilities.xhtml.patch (17.9 KB) - added by jdb 4 years ago.
Patch for the articles in the section 'Utilities' of the core howto
rdbms.xhtml.patch (1.9 KB) - added by jdb 4 years ago.
Two fixes in the row.xhtml lore input.
appendix.xhtml.patch (2.3 KB) - added by jdb 4 years ago.
Fixes in the glossary
pb.xhtml.patch (97.8 KB) - added by jdb 4 years ago.
Adapted the lore input for the articles in the Perspective Broker section
high-level.xhtml.patch (22.9 KB) - added by jdb 4 years ago.
Adapted the lore input of the articles in the "High-Level Twisted" section of the core howto
core-howto.xhtml.patch (80.6 KB) - added by jdb 4 years ago.
core-howto2.xhtml.patch (79.8 KB) - added by jdb 4 years ago.

Download all attachments as: .zip

Change History (45)

comment:1 Changed 4 years ago by khorn

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

comment:2 Changed 4 years ago by Screwtape

  • Owner changed from glyph to Screwtape
  • Status changed from new to assigned

comment:3 Changed 4 years ago by screwtape

  • Author set to screwtape
  • Branch set to branches/lore2sphinx-projects-core-howto-4568

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

comment:4 Changed 4 years ago by khorn

  • Milestone set to Lore to Sphinx

comment:5 Changed 4 years ago by Screwtape

  • Keywords documentation review added
  • Milestone Lore to Sphinx deleted
  • Owner Screwtape deleted
  • Status changed from assigned to new

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.

comment:6 Changed 4 years ago by jml

  • Keywords review removed
  • Owner set to Screwtape

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.

comment:7 Changed 4 years ago by 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.

Changed 4 years ago by jdb

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

Changed 4 years ago by jdb

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

comment:8 Changed 4 years ago by jdb

  • Keywords review added
  • Owner Screwtape deleted

Changed 4 years ago by jdb

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

Changed 4 years ago by jdb

Two fixes in the row.xhtml lore input.

Changed 4 years ago by jdb

Fixes in the glossary

Changed 4 years ago by jdb

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

Changed 4 years ago by jdb

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

comment:9 Changed 4 years ago by 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.

comment:10 Changed 4 years ago by exarkun

  • Keywords review removed
  • Owner set to jdb

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

comment:11 Changed 4 years ago by jdb

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

Changed 4 years ago by jdb

comment:12 Changed 4 years ago by jdb

  • Keywords review added
  • Owner jdb deleted

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.

comment:13 Changed 4 years ago by thijs

  • Keywords review removed
  • Owner set to jdb

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 

comment:14 Changed 4 years ago by jdb

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

Changed 4 years ago by jdb

comment:15 Changed 4 years ago by khorn

  • Keywords review added

comment:16 Changed 4 years ago by glyph

  • Owner jdb deleted

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

comment:17 Changed 3 years ago by exarkun

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

refs #4568

comment:18 Changed 3 years ago by exarkun

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

refs #4568
refs #4863

comment:19 Changed 3 years ago by exarkun

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

refs #4568
refs #4864

comment:20 Changed 3 years ago by exarkun

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

refs #4865
refs #4568

comment:21 Changed 3 years ago by exarkun

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

refs #4866
refs #4568

comment:22 Changed 3 years ago by exarkun

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

refs #4568
refs #4867

comment:23 Changed 3 years ago by exarkun

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

refs #4868
refs #4568

comment:24 Changed 3 years ago by exarkun

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

refs #4568
refs #4869

comment:25 Changed 3 years ago by exarkun

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

refs #4870
refs #4568

comment:26 Changed 3 years ago by exarkun

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

refs #4871
refs #4568

comment:27 Changed 3 years ago by exarkun

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

refs #4568
refs #4872

comment:28 Changed 3 years ago by exarkun

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

refs #4568
refs #4873

comment:29 Changed 3 years ago by exarkun

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

refs #4874
refs #4568

comment:30 Changed 3 years ago by exarkun

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

refs #4568
refs #4875

comment:31 Changed 3 years ago by exarkun

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

refs #4568
refs #4876

comment:32 Changed 3 years ago by exarkun

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

refs #4568
refs #4877

comment:33 Changed 3 years ago by exarkun

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

refs #4568
refs #4878

comment:34 Changed 3 years ago by exarkun

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

refs #4568
refs #4879

comment:35 Changed 3 years ago by exarkun

  • Keywords review removed
  • Resolution set to duplicate
  • Status changed from new to closed

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

comment:36 Changed 3 years ago by <automation>

Note: See TracTickets for help on using tickets.