Ticket #1712 (assigned defect)

Opened 4 years ago

Last modified 7 weeks ago

Twisted overview graph shows Xish

Reported by: ralphm Owned by: thijs
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: exarkun, thijs, radix Branch: branches/overview-graph-1712
Author: thijs Launchpad Bug:

Description

The graphical overview at  http://twistedmatrix.com/projects/core/documentation/howto/overview.html still shows Xish as a separate component. However, it has been folder into Words a while back.

Change History

  Changed 4 years ago by exarkun

  • keywords documentation added
  • owner changed from glyph to tekNico

follow-up: ↓ 4   Changed 4 years ago by exarkun

It also shows Twisted.Flow, Twisted.Protocols as containing all the protocol implementations, half the executables in the wrong place, and implies "String ports" is a fundamental part of core twisted. Basically half this picture is wrong. The whole thing needs a going over.

  Changed 4 years ago by ralphm

  • cc exarkun added

Would 2.3 be a good target for this?

in reply to: ↑ 2   Changed 2 years ago by thijs

  • cc thijs added

Replying to exarkun:

Basically half this picture is wrong. The whole thing needs a going over.

Are the source files for those diagrams available?

  Changed 2 years ago by exarkun

There's doc/core/img/twisted-overview.dia, that's probably it.

  Changed 22 months ago by thijs

  • status changed from new to assigned
  • owner changed from tekNico to thijs

  Changed 22 months ago by thijs

  • branch set to branches/overview-graph-1712
  • branch_author set to thijs

(In [25338]) Branching to 'overview-graph-1712'

  Changed 22 months ago by thijs

  • keywords documentation, review added; documentation removed
  • owner thijs deleted
  • status changed from assigned to new

Removed xish and flow from the diagram in r25339, I'll need a better description/suggestion to restructure the diagram. Putting it up for review.

  Changed 22 months ago by ralphm

Your change indeed fixes the problem described in this ticket. Is your question whether this diagram should have more changes? I think so. Should it go into this ticket? I'd agree on widening the scope of this ticket.

  Changed 22 months ago by exarkun

  • keywords documentation added; documentation, review removed
  • owner set to radix

Yes. The diagram still needs a lot of work. Even with xish in the right place now, it doesn't really convey useful information to someone trying to learn about Twisted. It's just a bunch of boxes and words and arrows.

We could remove it entirely or someone who's familiar with the various abstractions in Twisted could try fixing it (perhaps by starting over from scratch) to be useful.

A couple other specific problems with the current form:

  • it includes mktap, which we've stopped documenting anywhere else
  • it talks about bin/lore instead of bin/lore/lore

There are doubtless other issues, but those are the two which I noticed first. Even if these are fixed, the diagram is still not useful (but the problems shouldn't be replicated in any future version).

As a roughly orthogonal issue, dia doesn't seem like the best format we could use for this kind of thing. I'd suggest svg for a future version (but whatever).

Speculatively reassigning this to someone who might fall into the familiar with the various abstractions in Twisted group.

  Changed 8 months ago by thijs

  • keywords documentation, review added; documentation removed
  • cc radix added

Assigning to radix for review then.

  Changed 8 months ago by radix

  • owner radix deleted
  • keywords documentation added; documentation, review removed

I'm not sure what I'm supposed to be reviewing here. It looks like this ticket is in need of implementation before I can review it.

  Changed 7 months ago by thijs

  • status changed from new to assigned
  • owner set to thijs

Let's include exarkun's suggestions and then hopefully merge:

  • it includes mktap, which we've stopped documenting anywhere else
  • it talks about bin/lore instead of bin/lore/lore

  Changed 7 months ago by exarkun

Other things that are wrong with the diagram:

  1. twisted.protocols no longer contains any of the protocols it talks about (except telnet, which is deprecated). Instead it should actually be listing at least some of the stuff (ftp and socks, anyway) from the "Other" box in the "Twisted.Servers" section.
  2. "Twisted.Servers"? What does that mean? Those look like more "Twisted Subprojects", except for "Other", which I think we should just drop.

  Changed 7 weeks ago by thijs

I suggest we redo it in .svg so it can be opened in other programs besides Dia, which doesn't allow me to edit the text in the trunk's file.

Note: See TracTickets for help on using tickets.