Ticket #4951 defect closed fixed

Opened 3 years ago

Last modified 3 years ago

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

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

Change History

1

  Changed 3 years ago by DefaultCC Plugin

  • cc jknight added

2

  Changed 3 years ago by habnabit

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

3

  Changed 3 years ago by habnabit

  • branch set to branches/docfix-4951
  • branch_author set to habnabit

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

4

follow-up: ↓ 9   Changed 3 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.

5

  Changed 3 years ago by tenth

  • branch changed from branches/docfix-4951 to branches/broken-doc-link-4951
  • branch_author changed from habnabit to tenth, habnabit

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

6

  Changed 3 years ago by tenth

  • branch changed from branches/broken-doc-link-4951 to branches/docfix-4951
  • branch_author changed from tenth, habnabit to habnabit

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

7

  Changed 3 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

8

  Changed 3 years ago by thijs

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

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.

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.

10

  Changed 3 years ago by thijs

  • branch changed from branches/docfix-4951 to branches/web-links-4951
  • branch_author changed from habnabit to thijs, habnabit

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

11

  Changed 3 years ago by thijs

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

12

  Changed 3 years ago by thijs

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

13

  Changed 3 years ago by thijs

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

 Build results. Up for review.

14

  Changed 3 years ago by jesstess

  • owner set to jesstess

15

follow-up: ↓ 17   Changed 3 years ago by jesstess

  • cc jesstess added
  • owner changed from jesstess to thijs
  • keywords documentation added; documentation, review removed

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.

16

  Changed 3 years ago by thijs

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

17

in reply to: ↑ 15 ; follow-up: ↓ 19   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. * 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.

18

  Changed 3 years ago by thijs

  • status changed from assigned to closed
  • resolution set to fixed

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

Author: thijs Reviewer: jesstess Fixes: #4951

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.