Opened 4 years ago

Closed 3 years ago

Last modified 3 years ago

#4951 defect closed fixed (fixed)

links in twisted.web docs are broken

Reported by: habnabit Owned by: thijs
Priority: normal Milestone:
Component: web Keywords: documentation
Cc: jknight, thijs, jesstess Branch: branches/web-links-4951
(diff, github, buildbot, log)
Author: thijs Launchpad Bug:

Description

Spidered the most recent docs; all of these links are broken in the documentation. Format is the document with broken links, followed by the broken links.

http://twistedmatrix.com/documents/current/web/howto/resource-templates.html
  http://twistedmatrix.com/documents/10.2.0/api/twisted.web.server.Resource.html

http://twistedmatrix.com/documents/current/web/howto/using-twistedweb.html
  http://twistedmatrix.com/documents/10.2.0/api/twisted.application.internet.TCPServer.html

http://twistedmatrix.com/documents/current/web/howto/web-overview.html
  http://twistedmatrix.com/documents/10.2.0/api/twisted.web.server.NOT_DONE_YET.html

http://twistedmatrix.com/documents/current/web/howto/xmlrpc.html
  http://twistedmatrix.com/documents/10.2.0/api/twisted.web.resource.Resources.html
  http://twistedmatrix.com/documents/10.2.0/api/twisted.web.xmlrpc.Binary.html
  http://twistedmatrix.com/documents/10.2.0/api/twisted.web.xmlrpc.Boolean.html
  http://twistedmatrix.com/documents/10.2.0/api/twisted.web.xmlrpc.DateTime.html

http://twistedmatrix.com/documents/10.2.0/api/twisted.web.client.html
  http://twistedmatrix.com/documents/10.2.0/api/twisted.web.client.WebClientContextFactory%200.html

Attachments (1)

twisted.web-links.patch (4.7 KB) - added by thijs 3 years ago.
against r32149

Download all attachments as: .zip

Change History (20)

comment:1 Changed 4 years ago by DefaultCC Plugin

  • Cc jknight added

comment:2 Changed 4 years ago by habnabit

The last link in this list is related to this new pydoctor issue:
https://bugs.launchpad.net/pydoctor/+bug/735275

comment:3 Changed 4 years ago by habnabit

  • Author set to habnabit
  • Branch set to branches/docfix-4951

(In [31117]) Branching to 'docfix-4951'

comment:4 follow-up: Changed 4 years ago by lvh

  1. In http://twistedmatrix.com/documents/current/web/howto/resource-templates.html:
    1. http://twistedmatrix.com/documents/10.2.0/api/twisted.web.server.Resource.html is because t.w.s.Resource is now t.w.resource.Resource
  2. In http://twistedmatrix.com/documents/current/web/howto/using-twistedweb.html:
    1. The TCPServer link is broken because its implementation does evil hackery to produce the classes, which confuses pydoctor into thinking they don't exist.
  3. In http://twistedmatrix.com/documents/current/web/howto/web-overview.html:
    1. The link to NOT_DONE_YET doesn't work because pydoctor doesn't generate that API doc at all. This can be fixed by adding __all__ to twisted.web.server. This is very similar to what happened to t.w.guard in #3904.
  4. In http://twistedmatrix.com/documents/current/web/howto/xmlrpc.html:
    1. The link to Resources is just... wrong. Should point to the singular, Resource.
    2. The links to Fault et al. should just be removed or pointed to the stdlib xmlrpclib docs. 01:30 < glyph> I'm not so sure that having aliases for Fault et. al. is actually a good idea, though. So let's leave that out of the docs :)
  5. Last one is already handled in previous comment.


comment:5 Changed 4 years ago by tenth

  • Author changed from habnabit to tenth, habnabit
  • Branch changed from branches/docfix-4951 to branches/broken-doc-link-4951

(In [31278]) Branching to 'broken-doc-link-4951'

comment:6 Changed 4 years ago by tenth

  • Author changed from tenth, habnabit to habnabit
  • Branch changed from branches/broken-doc-link-4951 to branches/docfix-4951

(Whoops, opened a branch with the wrong ticket number! Please disregard my changes here.)

comment:7 Changed 4 years ago by tenth

Though, please note that #1, the broken link(s) in http://twistedmatrix.com/documents/current/web/howto/resource-templates.html are being addressed in #4968.

Changed 3 years ago by thijs

against r32149

comment:8 Changed 3 years ago by thijs

  • Cc thijs added
  • Owner set to thijs
  • Status changed from new to assigned

comment:9 in reply to: ↑ 4 Changed 3 years ago by thijs

It seems no work was done in the branch associated with this ticket so I attached a new patch.

Replying to lvh:

  1. In http://twistedmatrix.com/documents/current/web/howto/resource-templates.html:
    1. http://twistedmatrix.com/documents/10.2.0/api/twisted.web.server.Resource.html is because t.w.s.Resource is now t.w.resource.Resource

fixed with attached patch.

  1. In http://twistedmatrix.com/documents/current/web/howto/using-twistedweb.html:
    1. The TCPServer link is broken because its implementation does evil hackery to produce the classes, which confuses pydoctor into thinking they don't exist.

Let's ignore this then?

  1. In http://twistedmatrix.com/documents/current/web/howto/web-overview.html:
    1. The link to NOT_DONE_YET doesn't work because pydoctor doesn't generate that API doc at all. This can be fixed by adding __all__ to twisted.web.server. This is very similar to what happened to t.w.guard in #3904.

#4966 was opened for this.

  1. In http://twistedmatrix.com/documents/current/web/howto/xmlrpc.html:
    1. The link to Resources is just... wrong. Should point to the singular, Resource.

fixed with attached patch.

  1. The links to Fault et al. should just be removed or pointed to the stdlib xmlrpclib docs. 01:30 < glyph> I'm not so sure that having aliases for Fault et. al. is actually a good idea, though. So let's leave that out of the docs :)

I'll remove it in a new branch I'll create for this ticket.

comment:10 Changed 3 years ago by thijs

  • Author changed from habnabit to thijs, habnabit
  • Branch changed from branches/docfix-4951 to branches/web-links-4951

(In [32152]) Branching to 'web-links-4951'

comment:11 Changed 3 years ago by thijs

(In [32153]) Apply twisted.web-links.patch, refs #4951

comment:12 Changed 3 years ago by thijs

(In [32185]) Remove xmlrpclib alias links, refs #4951

comment:13 Changed 3 years ago by thijs

  • Author changed from thijs, habnabit to thijs
  • Keywords review added
  • Owner thijs deleted
  • Status changed from assigned to new

Build results. Up for review.

comment:14 Changed 3 years ago by jesstess

  • Owner set to jesstess

comment:15 follow-up: Changed 3 years ago by jesstess

  • Cc jesstess added
  • Keywords review removed
  • Owner changed from jesstess to thijs

Thanks for getting this finished and the bonus doc standards cleanup, thijs.

  • The new http://wsgi.org link is a meta refresh to http://wsgi.org/wsgi/, which was the old link.
  • NOT_DONE_YET got a new ticket, but the TCPServer and WebClientContextFactory links from the ticket description are still broken. Either this ticket should stay open until they are fixed, or they should get their own tickets.

Other than that, looks great, please merge.

comment:16 Changed 3 years ago by thijs

(In [32190]) address review comments, add news file. refs #4951

comment:17 in reply to: ↑ 15 ; follow-up: Changed 3 years ago by thijs

  • Status changed from new to assigned

Replying to jesstess:

Thanks for getting this finished and the bonus doc standards cleanup, thijs.

Reverted this to the old link.

  • NOT_DONE_YET got a new ticket, but the TCPServer and WebClientContextFactory links from the ticket description are still broken. Either this ticket should stay open until they are fixed, or they should get their own tickets.

I've removed the API link for TCPServer and I'll open a new ticket for the WebClientContextFactory issue because it's probably not a strict doc issue and needs some code changes.

Other than that, looks great, please merge.

thanks for the review.

comment:18 Changed 3 years ago by thijs

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

(In [32192]) Merge web-links-4951: Correct some broken links in the web howto documents.

Author: thijs
Reviewer: jesstess
Fixes: #4951

comment:19 in reply to: ↑ 17 Changed 3 years ago by thijs

Replying to thijs:

I've removed the API link for TCPServer

Related ticket for this: #4965

and I'll open a new ticket for the WebClientContextFactory issue because it's probably not a strict doc issue and needs some code changes.

I'm not sure where to file this ticket, pydoctor or twisted..

Note: See TracTickets for help on using tickets.