links in twisted.web docs are broken

[habnabit]

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

[habnabit]

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

[habnabit]

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

[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.

[tenth]

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

[tenth]

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

[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.

[thijs]

against r32149

[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.

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.

Let's ignore this then?

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.

#4966 was opened for this.

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.

fixed with attached patch.

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 :)

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

[thijs]

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

[thijs]

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

[thijs]

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

[thijs]

 Build results. Up for review.

[jesstess]

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.

[thijs]

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

[thijs]

Replying to jesstess:

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.

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.

[thijs]

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

Author: thijs Reviewer: jesstess Fixes: #4951

[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..