Merge ~cjwatson/launchpad:doctest-comments-in-narrative into launchpad:master

[Colin Watson]

Move doctest comments to narrative

Pacifies a number of lp-lint-doctest errors.

[Ioana Lasc (ilasc)]

review: Approve

diff --git a/lib/lp/answers/stories/distribution-package-answer-contact.txt b/lib/lp/answers/stories/distribution-package-answer-contact.txt
index 048e495..2aa64a0 100644
--- a/lib/lp/answers/stories/distribution-package-answer-contact.txt
+++ b/lib/lp/answers/stories/distribution-package-answer-contact.txt
@@ -13,7 +13,9 @@ contacts as well as the distribution answer contacts.
     >>> from lp.services.worlddata.interfaces.language import ILanguageSet
     >>> login('[e-mail]')
     >>> ubuntu = getUtility(IDistributionSet).getByName('ubuntu')
-    >>> # Answer contacts must speak a language
+
+Answer contacts must speak a language.
+
     >>> user = getUtility(ILaunchBag).user
     >>> user.addLanguage(getUtility(ILanguageSet)['en'])
     >>> ubuntu.addAnswerContact(user, user)
diff --git a/lib/lp/answers/stories/faq-browse-and-search.txt b/lib/lp/answers/stories/faq-browse-and-search.txt
index 555aa33..fab6403 100644
--- a/lib/lp/answers/stories/faq-browse-and-search.txt
+++ b/lib/lp/answers/stories/faq-browse-and-search.txt
@@ -12,7 +12,8 @@ page on Launchpad to try to get some help. She clicks the
 find her problem there (surely playing a DVD must be common thing to do
 with a computer these days).
 
-    >>> # Kubuntu must enable answers to access questions.
+Kubuntu must enable answers to access questions.
+
     >>> from zope.component import getUtility
     >>> from lp.app.enums import ServiceUsage
     >>> from lp.registry.interfaces.distribution import IDistributionSet
diff --git a/lib/lp/answers/stories/question-browse-and-search.txt b/lib/lp/answers/stories/question-browse-and-search.txt
index ba3b8f9..cbbfaec 100644
--- a/lib/lp/answers/stories/question-browse-and-search.txt
+++ b/lib/lp/answers/stories/question-browse-and-search.txt
@@ -17,7 +17,8 @@ Average Joe has recently installed Kubuntu. He has a problem with his
 system and goes to the Kubuntu's support page in Launchpad to see if
 somebody had a similar problem.
 
-    >>> # Kubuntu must enable answers to access questions.
+Kubuntu must enable answers to access questions.
+
     >>> from zope.component import getUtility
     >>> from lp.app.enums import ServiceUsage
     >>> from lp.registry.interfaces.distribution import IDistributionSet
@@ -429,7 +430,8 @@ The exact question they were searching for is displayed!
 If the user didn't make any questions on the product, a message
 informing them of this fact is displayed.
 
-    >>> # gnmomebaker must enable answers to access questions.
+gnomebaker must enable answers to access questions.
+
     >>> from lp.registry.interfaces.product import IProductSet
     >>> login('[e-mail]')
     >>> getUtility(IProductSet)['gnomebaker'].answers_usage = (
diff --git a/lib/lp/answers/stories/question-search-multiple-languages.txt b/lib/lp/answers/stories/question-search-multiple-languages.txt
index 5188300..4d13a57 100644
--- a/lib/lp/answers/stories/question-search-multiple-languages.txt
+++ b/lib/lp/answers/stories/question-search-multiple-languages.txt
@@ -93,7 +93,8 @@ Arabic and is written from right-to-left.
 When the project has no questions to search, we do not show the
 language controls.
 
-    >>> # Kubuntu must enable answers to access questions.
+Kubuntu must enable answers to access questions.
+
     >>> from zope.component import getUtility
     >>> from lp.app.enums import ServiceUsage
     >>> from lp.registry.interfaces.distribution import IDistributionSet
diff --git a/lib/lp/app/doc/menus.txt b/lib/lp/app/doc/menus.txt
index 69f1036..8cf0d3a 100644
--- a/lib/lp/app/doc/menus.txt
+++ b/lib/lp/app/doc/menus.txt
@@ -1064,7 +1064,9 @@ If we try a navigation menu lookup on an object without a canonical url
 or a navigation menu adapter, then no menu will be returned, and no
 error will be raised by the template.
 
-    >>> # Needed so the IPathAdapter can be applied to this view.
+``@implementer(Interface)`` is needed so the ``IPathAdapter`` can be applied
+to this view.
+
     >>> @implementer(Interface)
     ... class MenulessView(LaunchpadView):
     ...     __launchpad_facetname__ = 'cookery'
diff --git a/lib/lp/app/stories/basics/xx-opstats.txt b/lib/lp/app/stories/basics/xx-opstats.txt
index 558131b..8a991db 100644
--- a/lib/lp/app/stories/basics/xx-opstats.txt
+++ b/lib/lp/app/stories/basics/xx-opstats.txt
@@ -248,7 +248,9 @@ also return a timeout Fault:
     ...         """))
     >>> output.getStatus()
     503
-    >>> # Reset the timeouts so +opstat doesn't die.
+
+Reset the timeouts so +opstats doesn't die.
+
     >>> base_test_data = config.pop('base_test_data')
     >>> report()
     503s: 1
diff --git a/lib/lp/blueprints/stories/blueprints/xx-editing.txt b/lib/lp/blueprints/stories/blueprints/xx-editing.txt
index dda782d..cf0a920 100644
--- a/lib/lp/blueprints/stories/blueprints/xx-editing.txt
+++ b/lib/lp/blueprints/stories/blueprints/xx-editing.txt
@@ -89,7 +89,6 @@ implementation status, estimated man days etc) of the specification.
     >>> back_link.url
     'http://blueprints.launchpad.test/firefox/+spec/extension-manager-upgrades'
     >>> browser.getControl('Definition Status').value = ['DRAFT']
-    >>> # browser.getControl('Estimated Developer Days').value = '5'
     >>> browser.getControl('Implementation Status').value = ['SLOW']
     >>> browser.getControl('Status Whiteboard').value = 'XXX'
     >>> browser.getControl('Change').click()
diff --git a/lib/lp/bugs/browser/tests/bugtask-edit-views.txt b/lib/lp/bugs/browser/tests/bugtask-edit-views.txt
index 6dfeb04..bc38836 100644
--- a/lib/lp/bugs/browser/tests/bugtask-edit-views.txt
+++ b/lib/lp/bugs/browser/tests/bugtask-edit-views.txt
@@ -67,9 +67,9 @@ changed to the corresponding source package.
     assigned to its source package 'linux-source-2.6.15'
     instead.
 
-    >>> # The sampledata is bad -- the original thunderbird task should
-    >>> # not exist, as there is no publication. Create one so we can
-    >>> # set it back.
+The sampledata is bad -- the original thunderbird task should not exist, as
+there is no publication. Create one so we can set it back.
+
     >>> ignored = factory.makeSourcePackagePublishingHistory(
     ...     distroseries=
     ...         ubuntu_thunderbird_task.target.distribution.currentseries,
diff --git a/lib/lp/bugs/doc/externalbugtracker-bugzilla-lp-plugin.txt b/lib/lp/bugs/doc/externalbugtracker-bugzilla-lp-plugin.txt
index ff7f280..b13e159 100644
--- a/lib/lp/bugs/doc/externalbugtracker-bugzilla-lp-plugin.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-bugzilla-lp-plugin.txt
@@ -171,10 +171,11 @@ The BugzillaLPPlugin ExternalBugTracker, like all other
 ExternalBugTrackers, has a getCurrentDBTime() method, which returns the
 current time on the remote server.
 
+It seems there's no way to create a UTC timestamp without monkey-patching
+the TZ environment variable. Rather than do that, we create our own datetime
+and work with that.
+
     >>> from datetime import datetime
-    >>> # It seems there's no way to create a UTC timestamp without
-    >>> # monkey-patching the TZ environment variable. Rather than do
-    >>> # that, we create our own datetime and work with that.
     >>> remote_time = datetime(2008, 5, 16, 16, 53, 20)
 
     >>> test_transport.utc_offset = 60**2
diff --git a/lib/lp/bugs/doc/externalbugtracker-bugzilla.txt b/lib/lp/bugs/doc/externalbugtracker-bugzilla.txt
index 7975431..b8a9226 100644
--- a/lib/lp/bugs/doc/externalbugtracker-bugzilla.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-bugzilla.txt
@@ -784,7 +784,9 @@ cases getRemoteProduct() returns None.
     >>> external_bugzilla = TestBugzilla()
     >>> external_bugzilla.bugzilla_bugs = {84: (
     ...     'RESOLVED', 'FIXED', 'MEDIUM', 'NORMAL')}
-    >>> # Make the buglist XML not include the product tag.
+
+Make the buglist XML not include the product tag.
+
     >>> external_bugzilla.bug_item_file = 'gnome_bug_li_item_noproduct.xml'
     >>> with external_bugzilla.responses():
     ...     external_bugzilla.initializeRemoteBugDB(['84'])
diff --git a/lib/lp/bugs/doc/externalbugtracker-trac-lp-plugin.txt b/lib/lp/bugs/doc/externalbugtracker-trac-lp-plugin.txt
index 4103661..4fdb9f7 100644
--- a/lib/lp/bugs/doc/externalbugtracker-trac-lp-plugin.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-trac-lp-plugin.txt
@@ -149,9 +149,10 @@ instance returns another time zone.
     ...     'http://example.com/', xmlrpc_transport=test_transport,
     ...     internal_xmlrpc_transport=TestInternalXMLRPCTransport())
 
+There doesn't seem to be a way to generate a UTC time stamp, without mocking
+around with the TZ environment variable.
+
     >>> from datetime import datetime
-    >>> # There doesn't seem to be a way to generate a UTC time stamp,
-    >>> # without mocking around with the TZ environment variable.
     >>> datetime.utcfromtimestamp(1207706521)
     datetime.datetime(2008, 4, 9, 2, 2, 1)
 
diff --git a/lib/lp/bugs/stories/bugs/bug-add-subscriber.txt b/lib/lp/bugs/stories/bugs/bug-add-subscriber.txt
index 752ccb9..bb5e0cf 100644
--- a/lib/lp/bugs/stories/bugs/bug-add-subscriber.txt
+++ b/lib/lp/bugs/stories/bugs/bug-add-subscriber.txt
@@ -124,7 +124,8 @@ Private teams can be subscribed to bugs. Any logged in user can see
 the private team in the subscribers list. Additionally if they are a member
 of the private team they can unsubscribe the team.
 
-    >>> # Create a private team with Foo Bar as the owner.
+Create a private team with Foo Bar as the owner.
+
     >>> from zope.component import getUtility
     >>> from lp.registry.interfaces.person import IPersonSet, PersonVisibility
     >>> login('[e-mail]')
diff --git a/lib/lp/bugs/stories/bugs/xx-bug-create-question.txt b/lib/lp/bugs/stories/bugs/xx-bug-create-question.txt
index b094569..f9ebcda 100644
--- a/lib/lp/bugs/stories/bugs/xx-bug-create-question.txt
+++ b/lib/lp/bugs/stories/bugs/xx-bug-create-question.txt
@@ -177,7 +177,8 @@ browser's back button, after creating a question, they are re-shown the
 form as it was. They resubmit the form, and are notified that a question
 could not be created.
 
-    >>> # Jokosher must enable answers to access questions.
+Jokosher must enable answers to access questions.
+
     >>> from zope.component import getUtility
     >>> from lp.app.enums import ServiceUsage
     >>> from lp.registry.interfaces.product import IProductSet
diff --git a/lib/lp/bugs/stories/bugtask-searches/xx-distribution-statistics-portlet.txt b/lib/lp/bugs/stories/bugtask-searches/xx-distribution-statistics-portlet.txt
index 628d87d..4d20e84 100644
--- a/lib/lp/bugs/stories/bugtask-searches/xx-distribution-statistics-portlet.txt
+++ b/lib/lp/bugs/stories/bugtask-searches/xx-distribution-statistics-portlet.txt
@@ -5,12 +5,13 @@ will be filtered to show just the bugs counted by that statistic.
 This document demonstrates the correct functioning of the various
 statistics links.
 
-Viewing critical bugs as Sample Person:
+Debian must enable the Launchpad bug tracker to access bugs.
 
-    >>> # Debian must enable the Launchpad bug tracker to access bugs.
     >>> from lp.testing.service_usage_helpers import set_service_usage
     >>> set_service_usage('debian', bug_tracking_usage='LAUNCHPAD')
 
+Viewing critical bugs as Sample Person:
+
     >>> print(http(br"""
     ... GET /debian/+bugs?field.status%3Alist=New&field.status%3Alist=Confirmed&field.importance%3Alist=Critical&search=Search HTTP/1.1
     ... Authorization: Basic dGVzdEBjYW5vbmljYWwuY29tOnRlc3Q=
diff --git a/lib/lp/bugs/stories/bugtask-searches/xx-listing-basics.txt b/lib/lp/bugs/stories/bugtask-searches/xx-listing-basics.txt
index 07c5522..0e4e7af 100644
--- a/lib/lp/bugs/stories/bugtask-searches/xx-listing-basics.txt
+++ b/lib/lp/bugs/stories/bugtask-searches/xx-listing-basics.txt
@@ -17,12 +17,13 @@ project.  Bugs in the Firefox product are displayed.
     1 Firefox does not support SVG
      Mozilla Firefox Low New
 
-Bug listings default to open bugtasks:
+Debian must enable the Launchpad bug tracker to access bugs.
 
-    >>> # Debian must enable the Launchpad bug tracker to access bugs.
     >>> from lp.testing.service_usage_helpers import set_service_usage
     >>> set_service_usage('debian', bug_tracking_usage='LAUNCHPAD')
 
+Bug listings default to open bugtasks:
+
     >>> user_browser.open('http://launchpad.test/debian/+bugs')
     >>> print_bugtasks(user_browser.contents)
     3 Bug Title Test mozilla-firefox (Debian) Unknown New
diff --git a/lib/lp/bugs/tests/bugs-emailinterface.txt b/lib/lp/bugs/tests/bugs-emailinterface.txt
index 9927229..b3e2402 100644
--- a/lib/lp/bugs/tests/bugs-emailinterface.txt
+++ b/lib/lp/bugs/tests/bugs-emailinterface.txt
@@ -2379,7 +2379,7 @@ transformed to be a bit more readable as a plain text document.
     ... Some Text. [[Macro()]]
     ... Don't push the [#boom red button]!
     ... See you in {{{#launchpad}}}.
-    ... """
+    ... """  # noqa
     >>> print(reformat_wiki_text(wiki_text))
     = Sample Wiki Text =
     Some Text.
diff --git a/lib/lp/code/doc/branch-merge-proposal-notifications.txt b/lib/lp/code/doc/branch-merge-proposal-notifications.txt
index e7134c2..8ee0a56 100644
--- a/lib/lp/code/doc/branch-merge-proposal-notifications.txt
+++ b/lib/lp/code/doc/branch-merge-proposal-notifications.txt
@@ -95,22 +95,27 @@ Email
 Jobs for notifications are automagically generated when the merge proposal
 is created.  When those jobs are run, the email is sent from the registrant.
 
-    >>> #clear any existing notifications
     >>> source_branch = bmp.source_branch
     >>> factory.makeRevisionsForBranch(source_branch, count=1)
     >>> target_branch = bmp.target_branch
-    >>> # Login to delete the proposal.
+
+Login to delete the proposal.
+
     >>> login('[e-mail]')
     >>> bmp.deleteProposal()
     >>> notifications = pop_notifications()
     >>> registrant = factory.makePerson(
     ...     displayname="Eric", email="[e-mail]")
-    >>> # To avoid needing to access branches, pre-populate diffs.
+
+To avoid needing to access branches, pre-populate diffs.
+
     >>> bmp = source_branch.addLandingTarget(
     ...     registrant, target_branch, needs_review=True)
     >>> previewdiff = factory.makePreviewDiff(merge_proposal=bmp)
     >>> transaction.commit()
-    >>> # Fake the update preview diff as done.
+
+Fake the update preview diff as done.
+
     >>> bmp.next_preview_diff_job.start()
     >>> bmp.next_preview_diff_job.complete()
     >>> [job] = list(getUtility(IBranchMergeProposalJobSource).iterReady())
@@ -169,7 +174,9 @@ in the email.
     ...     review_requests=reviewers, needs_review=True)
     >>> previewdiff = factory.makePreviewDiff(merge_proposal=bmp)
     >>> transaction.commit()
-    >>> # Fake the update preview diff as done.
+
+Fake the update preview diff as done.
+
     >>> bmp.next_preview_diff_job.start()
     >>> bmp.next_preview_diff_job.complete()
     >>> [job] = list(getUtility(IBranchMergeProposalJobSource).iterReady())
diff --git a/lib/lp/code/doc/codeimport-job.txt b/lib/lp/code/doc/codeimport-job.txt
index e28e6d8..1ce112d 100644
--- a/lib/lp/code/doc/codeimport-job.txt
+++ b/lib/lp/code/doc/codeimport-job.txt
@@ -189,8 +189,9 @@ possible.
     >>> from pytz import UTC
     >>> pending_job = reviewed_import.import_job
     >>> future_date = datetime(2100, 1, 1, tzinfo=UTC)
-    >>> # ICodeImportJob does not expose date_due,
-    >>> # so we must use removeSecurityProxy.
+
+ICodeImportJob does not expose date_due, so we must use removeSecurityProxy.
+
     >>> removeSecurityProxy(pending_job).date_due = future_date
     >>> new_events = NewEvents()
 
diff --git a/lib/lp/code/doc/codereviewcomment.txt b/lib/lp/code/doc/codereviewcomment.txt
index 263f73e..f12bcdf 100644
--- a/lib/lp/code/doc/codereviewcomment.txt
+++ b/lib/lp/code/doc/codereviewcomment.txt
@@ -49,7 +49,8 @@ Comments can be marked as replies to particular comments.
 When comments are added, a job is created to send the emails to the
 subscribers of the merge proposal.
 
-    >>> # Needed for now to make the iterReady show the jobs.
+Needed for now to make the iterReady show the jobs.
+
     >>> factory.makeRevisionsForBranch(merge_proposal.source_branch)
     >>> factory.makeRevisionsForBranch(merge_proposal.target_branch)
     >>> from lp.code.tests.helpers import mark_all_merge_proposal_jobs_done
diff --git a/lib/lp/code/stories/branches/package-branch-merges-with-product-branches.txt b/lib/lp/code/stories/branches/package-branch-merges-with-product-branches.txt
index 9dfe4e0..f676238 100644
--- a/lib/lp/code/stories/branches/package-branch-merges-with-product-branches.txt
+++ b/lib/lp/code/stories/branches/package-branch-merges-with-product-branches.txt
@@ -13,8 +13,10 @@ and vice versa.
     >>> b1_name = b1.unique_name
     >>> b2_url = canonical_url(b2)
     >>> b2_name = b2.unique_name
-    >>> # XXX TimPenhey 2009-05-15 bug=376851
-    >>> # Need more than one package and product branch to show links.
+
+XXX TimPenhey 2009-05-15 bug=376851
+Need more than one package and product branch to show links.
+
     >>> ignored = factory.makePackageBranch(sourcepackage=b1.sourcepackage)
     >>> ignored = factory.makeProductBranch(product=b1.product)
     >>> logout()
diff --git a/lib/lp/code/stories/branches/xx-branch-listings.txt b/lib/lp/code/stories/branches/xx-branch-listings.txt
index 1df95ae..7c49fba 100644
--- a/lib/lp/code/stories/branches/xx-branch-listings.txt
+++ b/lib/lp/code/stories/branches/xx-branch-listings.txt
@@ -388,7 +388,9 @@ both the series link in the first column with the branch unique name.
 
     >>> browser.open('http://code.launchpad.test/gnome-terminal')
     >>> table = find_tag_by_id(browser.contents, 'branchtable')
-    >>> # The development focus is always first.
+
+The development focus is always first.
+
     >>> row = table.tbody.find_all('tr')[0]
     >>> cols = row.find_all('td')
     >>> print(extract_text(cols[0]))
diff --git a/lib/lp/code/stories/branches/xx-branchmergeproposal-listings.txt b/lib/lp/code/stories/branches/xx-branchmergeproposal-listings.txt
index 6182e73..65172c7 100644
--- a/lib/lp/code/stories/branches/xx-branchmergeproposal-listings.txt
+++ b/lib/lp/code/stories/branches/xx-branchmergeproposal-listings.txt
@@ -39,7 +39,9 @@ Make two proposals for bob, one needing review, and one approved.
     ...     owner=bob, product=fooix, name='review')
     >>> proposal = branch.addLandingTarget(bob, trunk)
     >>> proposal.requestReview()
-    >>> # Ensure the date_created is later to ensure stable ordering.
+
+Ensure the date_created is later to ensure stable ordering.
+
     >>> from zope.security.proxy import removeSecurityProxy
     >>> from datetime import timedelta
     >>> removeSecurityProxy(proposal).date_created += timedelta(1)
diff --git a/lib/lp/code/stories/branches/xx-claiming-team-code-reviews.txt b/lib/lp/code/stories/branches/xx-claiming-team-code-reviews.txt
index 41f91b3..3e63b18 100644
--- a/lib/lp/code/stories/branches/xx-claiming-team-code-reviews.txt
+++ b/lib/lp/code/stories/branches/xx-claiming-team-code-reviews.txt
@@ -5,7 +5,8 @@ When a team has been requested to review a merge proposal, any member of that
 team can claim that review.  This can be done by clicking on the "[Review]"
 link shown in the reviewer table for the team.
 
-    >>> # Logging in as an admin helps with setting things up.
+Logging in as an admin helps with setting things up.
+
     >>> login('[e-mail]')
     >>> eric = factory.makePerson(
     ...     name="eric", email="[e-mail]",
diff --git a/lib/lp/code/stories/branches/xx-code-review-comments.txt b/lib/lp/code/stories/branches/xx-code-review-comments.txt
index d0575b0..9cc4178 100644
--- a/lib/lp/code/stories/branches/xx-code-review-comments.txt
+++ b/lib/lp/code/stories/branches/xx-code-review-comments.txt
@@ -1,9 +1,9 @@
 Code Review Comments
 ====================
 
-Set up required objects
+Set up required objects.  We need to be admin to add a landing target to a
+random branch.
 
-    >>> # We need to be admin to add a landing target to a random branch
     >>> login('[e-mail]')
     >>> eric = factory.makePerson(
     ...     name="eric", email="[e-mail]",
diff --git a/lib/lp/code/stories/branches/xx-person-portlet-teambranches.txt b/lib/lp/code/stories/branches/xx-person-portlet-teambranches.txt
index c071545..1b8a2bc 100644
--- a/lib/lp/code/stories/branches/xx-person-portlet-teambranches.txt
+++ b/lib/lp/code/stories/branches/xx-person-portlet-teambranches.txt
@@ -12,7 +12,9 @@ and only teams that have branches are shown.
     ...     name="eric", email="[e-mail]",
     ...     displayname="Eric the Viking")
     >>> vikings = factory.makeTeam(name="vikings", owner=eric)
-    >>> # Also give vikings a cool icon.
+
+Also give vikings a cool icon.
+
     >>> icon = factory.makeLibraryFileAlias(
     ...     filename='vikings.png', content_type='image/png')
     >>> from lp.testing import run_with_login
diff --git a/lib/lp/code/stories/codeimport/xx-codeimport-results.txt b/lib/lp/code/stories/codeimport/xx-codeimport-results.txt
index e78f26c..0324baf 100644
--- a/lib/lp/code/stories/codeimport/xx-codeimport-results.txt
+++ b/lib/lp/code/stories/codeimport/xx-codeimport-results.txt
@@ -51,8 +51,9 @@ Each of the lines is prefixed with a tick if the result status was
 success, or a cross if the status was a failure.  The title of the image
 is the text of the failure or success type.
 
-    >>> # The ordering here is dependant on the order the status values
-    >>> # are declared in the enumeration.
+The ordering here is dependent on the order the status values are declared
+in the enumeration.
+
     >>> for img in import_results.find_all('img'):
     ...     print(img)
     <img src="/@@/no" title="Unsupported feature"/>
diff --git a/lib/lp/code/stories/feeds/xx-revision-atom.txt b/lib/lp/code/stories/feeds/xx-revision-atom.txt
index 52b29f2..179a8eb 100644
--- a/lib/lp/code/stories/feeds/xx-revision-atom.txt
+++ b/lib/lp/code/stories/feeds/xx-revision-atom.txt
@@ -16,8 +16,10 @@ Create some specific branches to use for this test
     >>> from lp.testing import time_counter
     >>> from datetime import datetime, timedelta
     >>> import pytz
-    >>> # Since the feed only shows revisions from the last 30 days, we
-    >>> # need recent revisions.
+
+Since the feed only shows revisions from the last 30 days, we need recent
+revisions.
+
     >>> initial_revision_date = datetime.now(pytz.UTC) - timedelta(days=10)
     >>> date_generator = time_counter(
     ...     initial_revision_date, timedelta(days=1))
diff --git a/lib/lp/registry/doc/private-team-roles.txt b/lib/lp/registry/doc/private-team-roles.txt
index 6919c9d..0595e4c 100644
--- a/lib/lp/registry/doc/private-team-roles.txt
+++ b/lib/lp/registry/doc/private-team-roles.txt
@@ -10,7 +10,8 @@ Bugs
 Bug subscriptions
 -----------------
 
-    >>> # Create the necessary teams.
+Create the necessary teams.
+
     >>> team_owner = factory.makePerson(name='team-owner')
     >>> from lp.registry.interfaces.person import (
     ...     IPersonSet,
@@ -141,7 +142,8 @@ Private teams can be subscribed to private PPAs.
     ...     owner=team_owner,
     ...     visibility=PersonVisibility.PRIVATE)
 
-    >>> # We must login as the archive owner to add the subscription.
+We must login as the archive owner to add the subscription.
+
     >>> ignored = login_person(team_owner)
     >>> subscription = private_archive.newSubscription(
     ...     subscriber=another_priv_team,
@@ -206,7 +208,8 @@ Maintainer/Owner
 
 A public team and a private team can be a project owner.
 
-    >>> # The registrant must be specified or it will default to the owner.
+The registrant must be specified or it will default to the owner.
+
     >>> product = factory.makeProduct(registrant=admin_user)
     >>> product.owner = public_team
     >>> product.owner = priv_team
diff --git a/lib/lp/registry/stories/distributionmirror/xx-distribution-mirrors.txt b/lib/lp/registry/stories/distributionmirror/xx-distribution-mirrors.txt
index f288178..bdeeb63 100644
--- a/lib/lp/registry/stories/distributionmirror/xx-distribution-mirrors.txt
+++ b/lib/lp/registry/stories/distributionmirror/xx-distribution-mirrors.txt
@@ -132,7 +132,9 @@ pending mirrors have never been probed.
     zope.security.interfaces.Unauthorized: ...
 
     >>> browser = setupBrowser(auth='Basic [e-mail]:test')
-    >>> # Register an unreviewed archive mirror.
+
+Register an unreviewed archive mirror.
+
     >>> browser.open('http://launchpad.test/ubuntu/+newmirror')
     >>> browser.getControl(
     ...     name='field.display_name').value = 'Kabul LUG mirror'
diff --git a/lib/lp/registry/stories/distroseries/xx-distroseries-index.txt b/lib/lp/registry/stories/distroseries/xx-distroseries-index.txt
index f5eaa6f..5a3af54 100644
--- a/lib/lp/registry/stories/distroseries/xx-distroseries-index.txt
+++ b/lib/lp/registry/stories/distroseries/xx-distroseries-index.txt
@@ -129,8 +129,9 @@ Upstream packaging portlet
 The distroseries page contains a portlet with information on the
 upstream packaging.
 
-    >>> # Note that warty's sourcecount is stale in sample data
-    >>> # which causes -2 need linking.
+Note that warty's sourcecount is stale in sample data which causes -2 need
+linking.
+
     >>> anon_browser.open('http://launchpad.test/ubuntu/warty')
     >>> print(extract_text(
     ...     find_tag_by_id(anon_browser.contents, 'series-packaging')))
diff --git a/lib/lp/registry/stories/team/xx-team-membership.txt b/lib/lp/registry/stories/team/xx-team-membership.txt
index a2d7fb3..ccab69b 100644
--- a/lib/lp/registry/stories/team/xx-team-membership.txt
+++ b/lib/lp/registry/stories/team/xx-team-membership.txt
@@ -106,8 +106,10 @@ pre-populated with the last comment.
 
     >>> url = '/~ubuntu-team/+member/kamion'
     >>> browser.getLink(url=url).click()
-    >>> # Do not use 'print' for the following test as it will eliminate potential
-    >>> # leading and trailing whitespace, which we don't want.
+
+Do not use 'print' for the following test as it will eliminate potential
+leading and trailing whitespace, which we don't want.
+
     >>> browser.getControl(name='comment').value
     'Arfie'
 
diff --git a/lib/lp/registry/stories/webservice/xx-private-team.txt b/lib/lp/registry/stories/webservice/xx-private-team.txt
index 05b9a89..1dbc817 100644
--- a/lib/lp/registry/stories/webservice/xx-private-team.txt
+++ b/lib/lp/registry/stories/webservice/xx-private-team.txt
@@ -84,7 +84,8 @@ Changing team visibility
 New teams when created have public visibility.  That attribute can be
 changed by admins and commercial admins but not by regular users.
 
-    >>> # Create a webservice object for commercial-admins.
+Create a webservice object for commercial-admins.
+
     >>> from zope.component import getUtility
     >>> from lp.testing import ANONYMOUS, login, logout
     >>> from lp.testing.pages import webservice_for_person
diff --git a/lib/lp/services/database/doc/multitablecopy.txt b/lib/lp/services/database/doc/multitablecopy.txt
index 074c942..618ebd7 100644
--- a/lib/lp/services/database/doc/multitablecopy.txt
+++ b/lib/lp/services/database/doc/multitablecopy.txt
@@ -9,7 +9,8 @@ may be interlinked through foreign keys.
     >>> from lp.services.database.multitablecopy import MultiTableCopy
     >>> from lp.services.database.sqlbase import cursor
 
-    >>> # Keep track of tables we'll want to clean up later
+Keep track of tables we'll want to clean up later.
+
     >>> tables_to_clean_up = []
 
 
@@ -409,7 +410,8 @@ This time we run to completion without problems.
     112  lots
     114  lots
 
-    >>> # To keep things simple, we erase the high values again:
+To keep things simple, we erase the high values again:
+
     >>> cur.execute("DELETE FROM numeric WHERE n > 100")
     >>> cur.execute("""
     ...     DELETE FROM textual WHERE NOT EXISTS (
@@ -659,5 +661,4 @@ The callbacks are called only while pouring, once per batch.
 Cleanup
 -------
 
-    >>> #postgresql.drop_tables(cursor(), tables_to_clean_up)
-
+    >>> postgresql.drop_tables(cursor(), tables_to_clean_up)
diff --git a/lib/lp/services/mail/doc/sending-mail.txt b/lib/lp/services/mail/doc/sending-mail.txt
index ad7e235..de0483f 100644
--- a/lib/lp/services/mail/doc/sending-mail.txt
+++ b/lib/lp/services/mail/doc/sending-mail.txt
@@ -29,7 +29,9 @@ Now let's look at the sent email:
     'Subject'
     >>> print(six.ensure_text(msg.get_payload(decode=True)))
     Content
-    >>> # Make sure bulk headers are set for vacation programs
+
+Make sure bulk headers are set for vacation programs.
+
     >>> msg['Precedence']
     'bulk'
 
diff --git a/lib/lp/soyuz/doc/gina.txt b/lib/lp/soyuz/doc/gina.txt
index f342cf3..ad2b8fa 100644
--- a/lib/lp/soyuz/doc/gina.txt
+++ b/lib/lp/soyuz/doc/gina.txt
@@ -196,9 +196,16 @@ Testing Source Package Results
 We should have more source packages in the database:
 
     >>> existing = 9
-    >>> hc = 13 - 2   # 2 packages fail
-    >>> bc = 9 - 3 - 2 + 1  # 3 packages are the same as in hoary, 2 fail,
-    ... #one that is imported forcefully (ubuntu-meta)
+
+Two packages fail.
+
+    >>> hc = 13 - 2
+
+Three packages are the same as in hoary; two fail; one is imported
+forcefully (ubuntu-meta).
+
+    >>> bc = 9 - 3 - 2 + 1
+
     >>> hc + bc
     16
     >>> count = SourcePackageRelease.select().count()
diff --git a/lib/lp/soyuz/stories/ppa/xx-ppa-private-teams.txt b/lib/lp/soyuz/stories/ppa/xx-ppa-private-teams.txt
index 47b7b2c..6989647 100644
--- a/lib/lp/soyuz/stories/ppa/xx-ppa-private-teams.txt
+++ b/lib/lp/soyuz/stories/ppa/xx-ppa-private-teams.txt
@@ -8,7 +8,8 @@ Activating Personal Package Archives for Private Teams
 Private teams can have PPAs and the process of activation is the same
 as for individuals and public teams.
 
-    >>> # Create a private team.
+Create a private team.
+
     >>> from zope.component import getUtility
     >>> from lp.registry.interfaces.person import (
     ...     IPersonSet, PersonVisibility, TeamMembershipPolicy)
diff --git a/lib/lp/translations/doc/poexport-request.txt b/lib/lp/translations/doc/poexport-request.txt
index 4841cb9..ac5ed50 100644
--- a/lib/lp/translations/doc/poexport-request.txt
+++ b/lib/lp/translations/doc/poexport-request.txt
@@ -164,7 +164,8 @@ Only the Spanish request is new, and that goes into the queue.
     pmount:cs
     pmount:es
 
-    >>> # Clean up the queue again.
+Clean up the queue again.
+
     >>> for request in IStore(POExportRequest).find(POExportRequest):
     ...     request.destroySelf()
 
diff --git a/lib/lp/translations/doc/poimport.txt b/lib/lp/translations/doc/poimport.txt
index 5b07995..8a0a109 100644
--- a/lib/lp/translations/doc/poimport.txt
+++ b/lib/lp/translations/doc/poimport.txt
@@ -86,7 +86,7 @@ This is the file that'll get imported.
     ...
     ... msgid "translator-credits"
     ... msgstr ""
-    ... ''' % datetime.datetime.now(UTC).isoformat())
+    ... ''' % datetime.datetime.now(UTC).isoformat())  # noqa
 
 We sometimes saw deadlocks as POFile statistics were updated after
 importing a template.  The operation would read all translation messages
@@ -257,7 +257,7 @@ validation errors.
     ... msgstr[1] "Bars %%d"
     ... msgstr[2] "Welsh power! %%d"
     ... msgstr[3] "We have four! %%d"
-    ... ''' % datetime.datetime.now(UTC).isoformat())
+    ... ''' % datetime.datetime.now(UTC).isoformat())  # noqa
 
 This is the dbschema that controls the validation of a translation.
 
@@ -439,7 +439,7 @@ For example, here's a gettext PO file with two headers.
     ...
     ... msgid "a"
     ... msgstr "b"
-    ... ''' % datetime.datetime.now(UTC).isoformat())
+    ... ''' % datetime.datetime.now(UTC).isoformat())  # noqa
     >>> eo_pofile = potemplate.newPOFile('eo')
     >>> warning_entry = translation_import_queue.addOrUpdateEntry(
     ...     'eo.po', pofile_with_warning, False, potemplate.owner,
@@ -660,7 +660,7 @@ We'll import a POFile with 3 plural forms into this POFile:
     ... msgstr[0] "First form %%d"
     ... msgstr[1] "Second form %%d"
     ... msgstr[2] "Third form %%d"
-    ... ''' % datetime.datetime.now(UTC).isoformat())
+    ... ''' % datetime.datetime.now(UTC).isoformat())  # noqa
 
 We now import this POFile as this language's translation for the soure
 package:
@@ -669,7 +669,9 @@ package:
     ...     pofile.path, pofile_with_plurals, True, person,
     ...     distroseries=distroseries, sourcepackagename=sourcepackagename,
     ...     potemplate=potemplate)
-    >>> # Allow Librarian to see the change.
+
+Allow the Librarian to see the change.
+
     >>> transaction.commit()
     >>> entry.pofile = pofile
     >>> entry.setStatus(RosettaImportStatus.APPROVED, rosetta_experts)
diff --git a/lib/lp/translations/stories/standalone/xx-person-editlanguages.txt b/lib/lp/translations/stories/standalone/xx-person-editlanguages.txt
index 6b674a7..e0e4fa8 100644
--- a/lib/lp/translations/stories/standalone/xx-person-editlanguages.txt
+++ b/lib/lp/translations/stories/standalone/xx-person-editlanguages.txt
@@ -70,8 +70,10 @@ Joao, a Brazilian, travels to Liechtenstein for business and views the
 languages page from there.
 
     >>> browser = setupBrowser('Basic [e-mail]:test')
-    >>> # Fake request from a Liechtenstein IP address by setting
-    >>> # X-Forwarded-For in the http header, like a proxy would.
+
+Fake request from a Liechtenstein IP address by setting X-Forwarded-For in
+the http header, like a proxy would.
+
     >>> browser.addHeader('X-Forwarded-For', '80.66.224.0')
     >>> browser.addHeader('Accept-Language', b'pt_br, Espa\xf1ol')
     >>> browser.open(
diff --git a/lib/lp/translations/stories/standalone/xx-pofile-translate-performance.txt b/lib/lp/translations/stories/standalone/xx-pofile-translate-performance.txt
index 5262d99..35a5fdc 100644
--- a/lib/lp/translations/stories/standalone/xx-pofile-translate-performance.txt
+++ b/lib/lp/translations/stories/standalone/xx-pofile-translate-performance.txt
@@ -48,5 +48,6 @@ Disable it for now.
     #>>> statement_count < query_counter.count < 150
     #True
 
-    >>> # Cleanup.
+Cleanup.
+
     >>> query_counter.unregister()
diff --git a/lib/lp/translations/stories/standalone/xx-product-export.txt b/lib/lp/translations/stories/standalone/xx-product-export.txt
index 60d4412..75eb760 100644
--- a/lib/lp/translations/stories/standalone/xx-product-export.txt
+++ b/lib/lp/translations/stories/standalone/xx-product-export.txt
@@ -39,8 +39,9 @@ Use of Launchpad Translations
 The Download link is not shown if the product does not use Launchpad
 Translations.
 
-    # Use the DB classes directly to avoid having to setup a zope interaction
-    # (i.e. login()) and bypass the security proxy.
+Use the DB classes directly to avoid having to setup a zope interaction
+(i.e. login()) and bypass the security proxy.
+
     >>> from lp.app.enums import ServiceUsage
     >>> from lp.registry.model.product import Product
     >>> product = Product.byName('evolution')
@@ -53,7 +54,8 @@ Translations.
     ...
     zope.testbrowser.browser.LinkNotFoundError
 
-    >>> # Restore previous state for subsequent tests, and verify
+Restore previous state for subsequent tests, and verify.
+
     >>> product.translations_usage = ServiceUsage.LAUNCHPAD
     >>> product.sync()
     >>> user_browser.open('http://translations.launchpad.test/evolution')
diff --git a/lib/lp/translations/stories/translationgroups/xx-translationgroups.txt b/lib/lp/translations/stories/translationgroups/xx-translationgroups.txt
index 96ebe8f..75d8725 100644
--- a/lib/lp/translations/stories/translationgroups/xx-translationgroups.txt
+++ b/lib/lp/translations/stories/translationgroups/xx-translationgroups.txt
@@ -1145,6 +1145,7 @@ cannot be handled.
     ... #, ycp-format
     ... msgid "This program is running as process number %1."
     ... msgstr "Hierdie program loop as prosesnommer %1."'''.encode('UTF-8')
+    ... # noqa
 
     >>> upload = admin_browser.getControl(name='file')
     >>> upload.add_file(BytesIO(af_file), 'application/msword', 'af.doc')
diff --git a/lib/lp/translations/utilities/doc/gettext_po_parser.txt b/lib/lp/translations/utilities/doc/gettext_po_parser.txt
index 7321806..835b05a 100644
--- a/lib/lp/translations/utilities/doc/gettext_po_parser.txt
+++ b/lib/lp/translations/utilities/doc/gettext_po_parser.txt
@@ -305,7 +305,7 @@ Parsing a PO template:
     ... #: foo/bar.c:42
     ... msgid "Foo"
     ... msgstr ""
-    ... """
+    ... """  # noqa
 
     >>> parser = POParser()
     >>> translation_file = parser.parse(content)
@@ -326,7 +326,7 @@ errors occur:
     ... #:foo/baz.c:42
     ... msgid "Baz"
     ... msgstr "abcdef"
-    ... """
+    ... """  # noqa
 
     >>> parser.parse(content + chunk2)
     ... # doctest: +IGNORE_EXCEPTION_MODULE_IN_PYTHON2
@@ -355,7 +355,7 @@ character.
     ... #: lib/regex.c:1367
     ... msgid "Success"
     ... msgstr "\xa6\xa8\xa5\\"
-    ... """
+    ... """  # noqa
 
     >>> translation_file = parser.parse(content)
 
@@ -427,7 +427,7 @@ the Content-Type field of the header.
     ... #: foo/bar.c: 50
     ... msgid "view \\302\\253${version_title}\\302\\273"
     ... msgstr ""
-    ... """
+    ... """  # noqa
 
     >>> translation_file = parser.parse(content)
 
@@ -545,7 +545,7 @@ Let's parse a Spanish PO file with an inverted plural formula.
     ... msgid_plural "files"
     ... msgstr[0] "plural translation"
     ... msgstr[1] "singular translation"
-    ... """
+    ... """  # noqa
 
     >>> parser = POParser(spanish_pluralformula)
     >>> translation_file = parser.parse(content)
diff --git a/lib/lp/translations/utilities/doc/gettext_po_parser_context.txt b/lib/lp/translations/utilities/doc/gettext_po_parser_context.txt
index 5ef1c80..23929ec 100644
--- a/lib/lp/translations/utilities/doc/gettext_po_parser_context.txt
+++ b/lib/lp/translations/utilities/doc/gettext_po_parser_context.txt
@@ -83,7 +83,7 @@ the same message in gettext, and we have to use msgctxt on one of them).
     ... msgid_plural "%%d files"
     ... msgstr[0] ""
     ... msgstr[1] ""
-    ... ''' % datetime.datetime.now(UTC).isoformat()).encode('UTF-8')
+    ... ''' % datetime.datetime.now(UTC).isoformat()).encode('UTF-8')  # noqa
 
 This file can now be correctly imported:
 
@@ -197,7 +197,7 @@ We can also import POFile with context messages.
     ... msgstr[0] "%%d translation"
     ... msgstr[1] "%%d translationes"
     ... msgstr[2] "%%d translations"
-    ... ''' % datetime.datetime.now(UTC).isoformat()).encode('UTF-8')
+    ... ''' % datetime.datetime.now(UTC).isoformat()).encode('UTF-8')  # noqa
 
 Importing this file succeeds.
 
diff --git a/lib/lp/translations/utilities/doc/kde-po-file-format.txt b/lib/lp/translations/utilities/doc/kde-po-file-format.txt
index 0e7a193..0f71e2b 100644
--- a/lib/lp/translations/utilities/doc/kde-po-file-format.txt
+++ b/lib/lp/translations/utilities/doc/kde-po-file-format.txt
@@ -116,7 +116,7 @@ message is preceded with '_n: ' (space at the end of the string is important).
     ...
     ... msgid "_n: entry\nentries"
     ... msgstr ""
-    ... ''' % ISO_FORMATTED_DATE).encode('UTF-8')
+    ... ''' % ISO_FORMATTED_DATE).encode('UTF-8')  # noqa
 
 And strangely, importing this file actually works, and format is changed
 to KDE PO format.
@@ -197,7 +197,7 @@ forms. They are simply newline-separated strings.
     ... msgid "_n: entry\nentries"
     ... msgstr "singular entry\n\nplural entries"
     ...
-    ... ''' % ISO_FORMATTED_DATE).encode('UTF-8')
+    ... ''' % ISO_FORMATTED_DATE).encode('UTF-8')  # noqa
 
 Importing this file succeeds, even if the number of %d printf specifications
 doesn't match: this is because this is now specially handled with KDE PO