Ticket #4568 enhancement closed duplicate

Opened 4 years ago

Last modified 3 years ago

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

core-introduction-tutorial.xhtml.patch Download (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 Download (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 Download (17.9 KB) - added by jdb 4 years ago.
Patch for the articles in the section 'Utilities' of the core howto
rdbms.xhtml.patch Download (1.9 KB) - added by jdb 4 years ago.
Two fixes in the row.xhtml lore input.
appendix.xhtml.patch Download (2.3 KB) - added by jdb 4 years ago.
Fixes in the glossary
pb.xhtml.patch Download (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 Download (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 Download (80.6 KB) - added by jdb 4 years ago.
core-howto2.xhtml.patch Download (79.8 KB) - added by jdb 4 years ago.

Change History

1

Changed 4 years ago by khorn

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

2

Changed 4 years ago by Screwtape

  • owner changed from glyph to Screwtape
  • status changed from new to assigned

3

Changed 4 years ago by screwtape

  • branch set to branches/lore2sphinx-projects-core-howto-4568
  • branch_author set to screwtape

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

4

Changed 4 years ago by khorn

  • milestone set to Lore to Sphinx

5

Changed 4 years ago by Screwtape

  • status changed from assigned to new
  • owner Screwtape deleted
  • keywords documentation review added
  • milestone Lore to Sphinx deleted

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.

6

Changed 4 years ago by jml

  • owner set to Screwtape
  • keywords review removed

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.

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

8

Changed 4 years ago by jdb

  • owner Screwtape deleted
  • keywords review added

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

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.

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?

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

12

Changed 4 years ago by jdb

  • owner jdb deleted
  • keywords review added

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.

13

Changed 4 years ago by thijs

  • owner set to jdb
  • keywords review removed

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 

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

15

Changed 3 years ago by khorn

  • keywords review added

16

Changed 3 years ago by glyph

  • owner jdb deleted

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

17

Changed 3 years ago by exarkun

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

refs #4568

18

Changed 3 years ago by exarkun

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

refs #4568 refs #4863

19

Changed 3 years ago by exarkun

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

refs #4568 refs #4864

20

Changed 3 years ago by exarkun

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

refs #4865 refs #4568

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

22

Changed 3 years ago by exarkun

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

refs #4568 refs #4867

23

Changed 3 years ago by exarkun

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

refs #4868 refs #4568

24

Changed 3 years ago by exarkun

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

refs #4568 refs #4869

25

Changed 3 years ago by exarkun

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

refs #4870 refs #4568

26

Changed 3 years ago by exarkun

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

refs #4871 refs #4568

27

Changed 3 years ago by exarkun

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

refs #4568 refs #4872

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

29

Changed 3 years ago by exarkun

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

refs #4874 refs #4568

30

Changed 3 years ago by exarkun

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

refs #4568 refs #4875

31

Changed 3 years ago by exarkun

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

refs #4568 refs #4876

32

Changed 3 years ago by exarkun

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

refs #4568 refs #4877

33

Changed 3 years ago by exarkun

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

refs #4568 refs #4878

34

Changed 3 years ago by exarkun

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

refs #4568 refs #4879

35

Changed 3 years ago by exarkun

  • keywords review removed
  • status changed from new to closed
  • resolution set to duplicate

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

36

Changed 3 years ago by <automation>

Note: See TracTickets for help on using tickets.