Opened 2 years ago

Last modified 17 months 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:
Author: Launchpad Bug:

Attachments (1)

ticket-5681.patch (1.1 KB) - added by hellojamieshin 17 months ago.

Download all attachments as: .zip

Change History (16)

comment:1 Changed 2 years ago by DefaultCC Plugin

  • Cc jknight added

comment:2 Changed 2 years ago by exarkun

  • Cc mwhudson added
  • Keywords easy removed

comment:3 Changed 17 months ago by rwall

  • 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 17 months ago by hellojamieshin

  • Owner set to hellojamieshin
  • Status changed from new to assigned

Changed 17 months ago by hellojamieshin

comment:5 Changed 17 months 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 17 months ago by thijs

  • 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 17 months ago by thijs

  • Owner hellojamieshin deleted
  • Status changed from assigned to new

comment:8 Changed 17 months 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 17 months ago by hellojamieshin

Oh and thank you for putting it up for review!

comment:10 Changed 17 months ago by acapnotic

  • Owner set to acapnotic
  • Status changed from new to assigned

comment:11 Changed 17 months ago by acapnotic

  • Keywords review removed
  • Owner changed from acapnotic to hellojamieshin
  • Status changed from assigned to new

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.

comment:12 Changed 17 months 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 17 months ago by 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.

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

comment:14 Changed 17 months ago by 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)

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

Note: See TracTickets for help on using tickets.