Opened 5 years ago

Last modified 4 years ago

#5681 defect new

Broken link to deliverBody in web client howto

Reported by: jesstess Owned by: hellojamieshin
Priority: normal Milestone:
Component: web Keywords: documentation easy
Cc: jknight, mwhudson Branch:

Attachments (1)

ticket-5681.patch (1.1 KB) - added by hellojamieshin 4 years ago.

Download all attachments as: .zip

Change History (16)

comment:1 Changed 5 years ago by DefaultCC Plugin

Cc: jknight added

comment:2 Changed 5 years ago by Jean-Paul Calderone

Cc: mwhudson added
Keywords: easy removed

comment:3 Changed 4 years ago by Richard Wall

Keywords: easy added

This looks like an easy ticket for gsoc applicants.

I notice that exarkun removed the easy keyword once before. Maybe that was a mistake or maybe it was intended that pydoctor could be updated to not require #fragments in api urls...but that would be a pydoctor bug.

Anyway I'll make it easy again.

comment:4 Changed 4 years ago by hellojamieshin

Owner: set to hellojamieshin
Status: newassigned

Changed 4 years ago by hellojamieshin

Attachment: ticket-5681.patch added

comment:5 Changed 4 years ago by hellojamieshin

[review request] I've attached a patch that addresses the issue. I ran the test suite and confirmed that all tests still pass.

comment:6 Changed 4 years ago by Thijs Triemstra

Keywords: review added

Thanks for your contribution hellojamieshin. In order to get your change reviewed, follow the instructions on ReviewProcess#Authors:Howtogetyourchangereviewed. I'll put your patch up for review for now.

comment:7 Changed 4 years ago by Thijs Triemstra

Owner: hellojamieshin deleted
Status: assignednew

comment:8 Changed 4 years ago by hellojamieshin

Hi thijs, thanks for the information, but I was told to put an attachment here since I don't have the commit access..

comment:9 Changed 4 years ago by hellojamieshin

Oh and thank you for putting it up for review!

comment:10 Changed 4 years ago by acapnotic

Owner: set to acapnotic
Status: newassigned

comment:11 Changed 4 years ago by acapnotic

Keywords: review removed
Owner: changed from acapnotic to hellojamieshin
Status: assignednew


Thanks for your patch, it applies cleanly and links to a page which actually exists, which is an unquestionable improvement.

However, hard-coding the full API documentation address instead of using the address auto-generated by lore's <code class="API"> directive has some disadvantages:

1) This link will always point to the /current/ version, so if someone is reading the howto for an older version, this link will send them to API docs for a newer version, which could be misleading.

2) the formatting may be slightly different than all the other API links in the document, since it's not contained in an element that matches CSS for code.API.

3) If anyone's building docs for offline use, this would still send them to

Unfortunately, the technical fix turns out to be not quite so easy after all: see ticket #6489.

In my opinion, having a broken link in a howto is pretty bad, and we shouldn't necessarily wait for someone to solve #6489, so we'll need a workaround or compromise.

The simplest thing would be to unlinkify it entirely (remove the class="API" and base="…" attributes). Response is still linked just above, so you could still get there.

The other would be to use your link to, because it's right for most people most of the time (an improvement over the current situation, which is never right), and wrap it in a <code> element (with no class="API") so the formatting is at least a little closer.

So this turned out to be longer than either of us expected for a one-line patch. Thanks again for taking a stab at it.

comment:12 Changed 4 years ago by hellojamieshin

Thanks, I also thought it was sketchy to hardcode url, but I wasn't sure if I was supposed to touch lore or any other parts since that doesn't seem like an easy documentation problem. Thank you for your comments!

comment:13 Changed 4 years ago by Richard Wall

Sorry for marking this an easy ticket. I should have checked the details.

pydoctor --html-write-function-pages does write method doc pages but they are in an unexpected place, because of the way Response is imported from _newclient.

So maybe the link used to work and broke when _newclient was introduced.

comment:14 Changed 4 years ago by Richard Wall

mwh fixed the problem in pydoctor and tomprince updated the buildbot pydoctor so the broken link should be fixed in the API docs for the next release (assuming that the releaser uses a trunk version of pydoctor)

But that change also seems to have broken some links within the API docs.

twisted.internet._sslverify._handleattrhelper: invalid ref to Certificate.hostFromTransport
twisted.internet._sslverify._handleattrhelper: invalid ref to Certificate.peerFromTransport
twisted.internet.ssl.CertificateOptions.__init__: invalid ref to OpenSSL.crypto.X509
twisted.protocols.amp._NoCertificate.options: invalid ref to twisted.internet.ssl.PrivateCertificate.options
twisted.spread.pb.Copyable.getTypeToCopyFor: invalid ref to getTypeToCopy
twisted.spread.pb.Copyable.jellyFor: invalid ref to getTypeToCopyFor
twisted.spread.pb.RemoteCopy: invalid ref to setCopyableState
twisted.spread.pb.Root.rootObject: invalid ref to pb.BrokerFactory
twisted.spread.pb.ViewPoint: invalid ref to remoteMessageReceived invalid ref to
twisted.trial.unittest.SynchronousTestCase.patch: invalid ref to addCleanup
twisted.trial.unittest.SynchronousTestCase.runTest: invalid ref to run
twisted.trial.unittest.SynchronousTestCase: invalid ref to run
twisted.trial.unittest.TestCase.__init__: invalid ref to SynchronousTestCase.runTest
twisted.trial.unittest.TestCase._runCleanups: invalid ref to addCleanup
twisted.trial.unittest.TestCase._undeprecateReactor: invalid ref to _deprecateReactor
twisted.trial.unittest.TestCase: invalid ref to assertFailure
twisted.web._newclient: invalid ref to Response.deliverBody
twisted.web.client.ResponseDone: invalid ref to Response.deliverBody
twisted.web.guard.DigestCredentialFactory.decode: invalid ref to twisted.cred.digest.DigestedCredentials
twisted.web.template.Tag._clone: invalid ref to Tag.clone
twisted.web.template.Tag.render: invalid ref to twisted.web.template.Element.lookupRenderMethod
twisted.web.template.Tag: invalid ref to twisted.web.template.Element.lookupRenderMethod invalid ref to Tag.fillSlots
twisted.web.template.slot: invalid ref to Tag.fillSlots

Eg currently contains a working link to Response.deliverBody, but that link is no longer there when building with trunk pydoctor.

Note: See TracTickets for help on using tickets.