Opened 6 years ago

Closed 5 years ago

#3418 enhancement closed fixed (fixed)

twisted.web examples directory explanation

Reported by: temoto Owned by:
Priority: normal Milestone:
Component: web Keywords: documentation examples
Cc: Branch:
Author: Launchpad Bug:

Description

Add at least the shortest description to the examples located at http://twistedmatrix.com/projects/web/documentation/examples/

at first i thought module docstrings would do nice, but examples don't have docstrings.

In example, it's hard to find that basic example usage of, well, twisted.web.client is in getpage.py.

Attachments (1)

doc-web-examples-index.patch (4.6 KB) - added by jesstess 5 years ago.

Download all attachments as: .zip

Change History (6)

Changed 5 years ago by jesstess

comment:1 Changed 5 years ago by jesstess

  • Keywords review added
  • Owner changed from jknight to jesstess

Added a description for each example and grouped them by topic. 3 examples were removed: webmon.py and tkwebmon.py, because it appears that twisted.web.monitor was removed entirely a while ago according to eg ticket 1878 and changeset 25431, and simple.tpl for not actually being an example but making it into the index anyway.

The handful of particularly lame descriptions are lame because it wasn't obvious me how to run those examples usefully; if someone give me better descriptions I'll happily include them and re-submit the patch.

It seems like webmon.py, tkwebmon.py, and simple.tpl should be removed from the examples/ directory - does a separate ticket need to be created for that?

comment:2 Changed 5 years ago by jesstess

  • Owner jesstess deleted

comment:3 Changed 5 years ago by exarkun

  • Keywords review removed
  • Owner set to exarkun
  • Status changed from new to assigned

This looks good to me. The descriptions don't even seem all that lame to me. :) They're descriptive enough to get people going in the right direction, I think (and the grouping also helps with that a lot).

I'm going to apply this patch. I agree about deleting webmon.py and tkwebmon.py. And I guess simple.tpl should go too, since it doesn't seem to be used by anything. I wonder what it used to be for. Ah, it's a lore template, presumably for the index. But I'm pretty sure we don't use it anymore, so yea it can go. I'll just delete them when I apply the attached patch, since this ticket is basically about making the web examples directory more coherent, and getting rid of stuff that is useless or broken will help with that. :)

comment:4 Changed 5 years ago by exarkun

  • Resolution set to fixed
  • Status changed from assigned to closed

(In [27241]) Apply doc-web-examples-index.patch and delete several broken/useless files

Author: jesstess
Reviewer: exarkun
Fixes: #3418

Group the web examples logically in the index file and add some
descriptive text for each one to make it easier to find particular
examples.

Also delete the webmon examples, since webmon was deleted a long
time ago, and delete the simple lore template which is no longer
used when generating these docs.

comment:5 Changed 4 years ago by <automation>

  • Owner exarkun deleted
Note: See TracTickets for help on using tickets.