Broken link to deliverBody in web client howto

[jesstess]

The API link to  http://twistedmatrix.com/documents/12.0.0/api/twisted.web.client.Response.deliverBody.html in the Receiving Responses section of  http://twistedmatrix.com/documents/current/web/howto/client.html is a 404.

I'd expect that to work, but apparently  http://twistedmatrix.com/documents/current/api/twisted.web.client.Response.html#deliverBody is the correct reference.

[rwall]

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.

[hellojamieshin]

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

[thijs]

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.

[hellojamieshin]

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

[hellojamieshin]

Oh and thank you for putting it up for review!

[acapnotic]

hellojamieshin,

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 twistedmatrix.com.

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 twistedmatrix.com/documents/current/, 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.

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

[rwall]

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.

•  https://twistedmatrix.com/documents/current/api/twisted.web._newclient.Response.deliverBody.html

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

[rwall]

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)

•  https://bazaar.launchpad.net/~mwhudson/pydoctor/dev/revision/596

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

•  https://buildbot.twistedmatrix.com/builders/documentation/builds/3281/steps/api-documentation/logs/new%20pydoctor%20errors

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
twisted.trial.runner.DestructiveTestSuite.run: invalid ref to TestSuite.run
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
twisted.web.template.slot.name: invalid ref to Tag.fillSlots
twisted.web.template.slot: invalid ref to Tag.fillSlots

Eg  https://twistedmatrix.com/documents/current/api/twisted.web.client.ResponseDone.html currently contains a working link to Response.deliverBody, but that link is no longer there when building with trunk pydoctor.

[rwall]

I created a new Pydoctor ticket:

•  https://bugs.launchpad.net/twisted-buildbot-configuration/+bug/1174312