Opened 7 years ago

Closed 6 years ago

#4578 enhancement closed wontfix (wontfix)

Improve lore2sphinx buildbot results for `projects/web2`

Reported by: khorn Owned by:
Priority: normal Milestone: Lore to Sphinx
Component: core Keywords: documentation
Cc: Branch: branches/improve-lore2sphinx-output-for-projects-web2-4578
branch-diff, diff-cov, branch-cov, buildbot
Author: khorn


like #4566, except for projects/web2

Change History (9)

comment:1 Changed 7 years ago by khorn

Author: khorn
Branch: branches/improve-lore2sphinx-output-for-projects-web2-4578

(In [29847]) Branching to 'improve-lore2sphinx-output-for-projects-web2-4578'

comment:2 Changed 7 years ago by khorn

(In [29848]) Adjust markup and fix some broken links.

Refs: #4578

comment:3 Changed 7 years ago by khorn

(In [29849]) Fix some spelling errors and some broken links.

Refs: #4578

comment:4 Changed 7 years ago by khorn

Keywords: documentation review added
Owner: Glyph deleted

comment:5 Changed 7 years ago by khorn

Milestone: Lore to Sphinx

comment:6 Changed 6 years ago by Screwtape

Keywords: review removed
Owner: set to khorn

I see a bunch of problems with the documentation that aren't your fault, but which I probably would have changed myself - things like shell-examples using a '%' prompt instead of a '$' prompt; references to 'twisted' or 'python' instead of 'Twisted' or 'Python', etc. Not really worth worrying about - but it *would* be nice to have a big ol' warning on the Web2 index page pointing people at the TwistedWebPlan page, so people know this is documentation for a deprecated library (much like core/howto/row.xhtml has).

Actual formatting problems (please fix these):

  • web2/howto/headers.html: The header "Lower level HTTP headers" starts with a '>'.
  • web2/howto/resource-apis.html:
    • The list item beginning "Response code. This should be one of..." has broken markup attempting to link to twisted.web2.responsecode.
    • In the list item beginning "Headers. The headers, as stored in..." has a typo: "automatiaclly" should be "automatically"
    • Under the heading "Request" there's a typo: "requst" should be "request".
  • web2/howto/object-traversal.html:
    • Under the heading "childFactory method", there's a bit of Python code describing a dict-based data structure. The line that defines quux=None needs an extra level of indent.
    • Under the heading "Dots in child names", "notimmediately" should be "not immediately"

Broken links (fix these if you have time, otherwise create a ticket):

  • web2/howto/object-traversal.html:
    • There are various references to t.w2.wsgi.createWSGIApplication, which sadly doesn't exist. Google suggests this is actually nevow.wsgi.createWSGIApplication, and as such probably shouldn't be mentioned - or at least, shouldn't be hyperlinked to the Twisted API docs.
    • Under the heading "IRequest.prepath and IRequest.postpath" there are links to API documentation for IRequest.prepath and IRequest.postpath; both are broken and I can't find where they should point to.
  • web2/howto/authentication.html:
    • Under the heading "Credential Factories" there's a bullet-point item about the decode() method, that refers to ICredential. That's a broken link, it should point to ICredentials (plural).
    • Under the heading "The HTTPAuthResource", the last bullet-point links to ICredentials.checkPassword. ICredentials defines no such method, although most of the interfaces inheriting from ICredentials do - certainly the ones likely to be used with HTTP Authentication. Not quite sure where this should link to.
    • Under the heading "Usage By Example", the second list-item mentions ICredentialCheckers. This is a broken link; it should point to ICredentialsChecker (plurals the wrong way around).

comment:7 Changed 6 years ago by Jean Daniel Browne

I re-read the pages, I see no formatting errors in the html output.

comment:8 Changed 6 years ago by <automation>

Owner: khorn deleted

comment:9 Changed 6 years ago by khorn

Resolution: wontfix
Status: newclosed

web2 is no more

Note: See TracTickets for help on using tickets.