Merge ~cjwatson/launchpad:doctest-reformat-headers into launchpad:master

[Colin Watson]

Reformat doctest headers in reStructuredText style

pocket-lint (and hence lp-lint-doctest) have been complaining about Moin-style headers in doctests for a long time, but we've never got round to fixing them all. Let's just get it over with.

Patch generated by:

  git grep -El '^= .+ = *$' | fgrep .txt | \
    xargs perl -pi -e 's/^= (.+) = *$/"$1\n" . ("=" x length($1))/e'
  git grep -El '^== .+ == *$' | fgrep .txt | \
    xargs perl -pi -e 's/^== (.+) == *$/"$1\n" . ("-" x length($1))/e'
  git grep -El '^=== .+ === *$' | fgrep .txt | \
    xargs perl -pi -e 's/^=== (.+) === *$/"$1\n" . ("." x length($1))/e'

[Colin Watson (cjwatson)]

Self-approving (trivial and mechanical).

review: Approve

diff --git a/configs/README.txt b/configs/README.txt
index 38e2893..4348000 100644
--- a/configs/README.txt
+++ b/configs/README.txt
@@ -1,10 +1,12 @@
-= Launchpad configs =
+Launchpad configs
+=================
 
 This directory defines the configurations used to run Launchpad
 applications in specific environments.
 
 
-== Environments ==
+Environments
+------------
 
 This directory stores configs. The config used is selected on startup
 using the LPCONFIG environment variable.
@@ -24,13 +26,15 @@ to do this if you are adding a new required config option to
 launchpad-lazr.conf.
 
 
-== LaunchpadConfig ==
+LaunchpadConfig
+---------------
 
 Launchpad uses a singleton LaunchpadConfig object to select the config
 to load and manage its state.
 
 
-=== Instance directories and process files ===
+Instance directories and process files
+......................................
 
 The directories in configs/ represent environment's config `instance`.
 Environment and instance are synonymous in this case. The instance is
@@ -60,7 +64,8 @@ All this information is available in the config object.
     '.../configs/development/launchpad-lazr.conf'
 
 
-=== Accessing the LaunchpadConfig in code ===
+Accessing the LaunchpadConfig in code
+.....................................
 
 The LaunchpadConfig singleton is exposed as config in its module.
 
@@ -87,7 +92,8 @@ You can learn more about lp.services.config in the doctest located at
     lib/canonical/launchpad/doc/canonical-config.txt
 
 
-=== Testing with LaunchpadConfig ===
+Testing with LaunchpadConfig
+............................
 
 Configurations are meant to be immutable--applications should never
 alter the config. Nor should tests. Older code and tests assumed
@@ -121,7 +127,8 @@ the config.
     'answers.launchpad.net'
 
 
-== lazr.conf schema and confs ==
+lazr.conf schema and confs
+--------------------------
 
 All Launchpad configs inherit from the Launchpad schema defined
 in ../lib/lp/services/config/schema-lazr.conf (it is symlinked
@@ -166,7 +173,8 @@ You can learn more about lazr.config in the doctest located at
     lib/canonical/lazr/doc/config.txt
 
 
-=== schema template and optional sections ===
+schema template and optional sections
+.....................................
 
 The schema can contain [<category>.template] sections that define a
 common set of keys and default value for category of sections.
@@ -238,7 +246,8 @@ Including just the section ([vhost.xmlrpc_private]) will suffice. In
 this case, the two keys were redefined.
 
 
-=== Implicit typing ===
+Implicit typing
+...............
 
 lazr.config support implicit typing so that the application does not
 need to coerce the config values:
@@ -264,7 +273,8 @@ the callsite must split the host:port compound object and coerce the
 port to an int.
 
 
-=== Config inheritance ===
+Config inheritance
+..................
 
 The lazr configurations in this directory descend from the
 Launchpad schema. This is a general outline of inheritance:
@@ -323,7 +333,8 @@ There are other configuration in this directory that are not
 listed here
 
 
-=== Viewing a configuration with lsconf.py ===
+Viewing a configuration with lsconf.py
+......................................
 
 You can view the complete configuration for an process using the
 lsconf.py utility to assemble the configuration from the lazr
diff --git a/lib/lp/answers/stories/faq-add.txt b/lib/lp/answers/stories/faq-add.txt
index c17df73..ac6023e 100644
--- a/lib/lp/answers/stories/faq-add.txt
+++ b/lib/lp/answers/stories/faq-add.txt
@@ -1,4 +1,5 @@
-== Creating a new FAQ ==
+Creating a new FAQ
+------------------
 
 New FAQs can be created for a project by users who have 'moderation'
 privileges. This includes answer contacts and the project's owner.
diff --git a/lib/lp/answers/stories/faq-browse-and-search.txt b/lib/lp/answers/stories/faq-browse-and-search.txt
index 51ba8eb..555aa33 100644
--- a/lib/lp/answers/stories/faq-browse-and-search.txt
+++ b/lib/lp/answers/stories/faq-browse-and-search.txt
@@ -1,6 +1,8 @@
-= Browsing and Searching FAQs =
+Browsing and Searching FAQs
+===========================
 
-== No FAQs ==
+No FAQs
+-------
 
 Miss Piggy decided to give Kubuntu a try based on the recommendations of
 Kermit. She wants to watch the wedding scene of The Muppets Take
@@ -36,7 +38,8 @@ Kubuntu:
     There are no FAQs for Kubuntu.
 
 
-== Browsing FAQs ==
+Browsing FAQs
+-------------
 
 She learns through Fozzie Bear that support for Kubuntu is really
 happening on the Ubuntu project.
@@ -94,7 +97,8 @@ The FAQ page has a link back to the FAQ listing:
     http://answers.launchpad.test/ubuntu/+faqs
 
 
-== Searching FAQs ==
+Searching FAQs
+--------------
 
 All FAQs listing have a search box at the top, where the user can
 enter keywords that be used to filter the displayed FAQs.
@@ -158,7 +162,8 @@ Following the link will show the questions results:
         Flash/Java web pages
 
 
-== Distribution Source Packages and FAQs ==
+Distribution Source Packages and FAQs
+-------------------------------------
 
 Altough distribution source packages aren't directly associated with
 FAQs. The 'All FAQs' link that appears in that context links to the
@@ -173,7 +178,8 @@ distribution FAQs.
     http://answers.launchpad.test/ubuntu/+faqs
 
 
-== Accessing an FAQ directly ==
+Accessing an FAQ directly
+-------------------------
 
 Asking for a non-existent FAQ or an invalid ID will raise a 404 error.
 
diff --git a/lib/lp/answers/stories/faq-edit.txt b/lib/lp/answers/stories/faq-edit.txt
index dc5969c..9a635d4 100644
--- a/lib/lp/answers/stories/faq-edit.txt
+++ b/lib/lp/answers/stories/faq-edit.txt
@@ -1,4 +1,5 @@
-= Editing FAQs =
+Editing FAQs
+============
 
 It is possible to modify the title, keywords and content of an existing
 FAQ. To do this, the user goes to the FAQ that they want to modify and
diff --git a/lib/lp/answers/stories/question-add-in-other-languages.txt b/lib/lp/answers/stories/question-add-in-other-languages.txt
index 9ec7b8d..47498e5 100644
--- a/lib/lp/answers/stories/question-add-in-other-languages.txt
+++ b/lib/lp/answers/stories/question-add-in-other-languages.txt
@@ -1,4 +1,5 @@
-= Asking questions in languages other than English =
+Asking questions in languages other than English
+================================================
 
 It is possible to ask questions in a language other than English. The
 'Ask a question' page has a pop-up where the user can select the language
diff --git a/lib/lp/answers/stories/question-browse-and-search.txt b/lib/lp/answers/stories/question-browse-and-search.txt
index 6c5bc69..ba3b8f9 100644
--- a/lib/lp/answers/stories/question-browse-and-search.txt
+++ b/lib/lp/answers/stories/question-browse-and-search.txt
@@ -1,4 +1,5 @@
-= Browsing and Searching Questions =
+Browsing and Searching Questions
+================================
 
 This story describes some common use cases about using the browsing and
 searching features of the Answer Tracker.
@@ -9,7 +10,8 @@ IP address, since we'll use that later.
     >>> browser.addHeader('X_FORWARDED_FOR', '196.36.161.227')
 
 
-== When Nobody Uses the Answer Tracker ==
+When Nobody Uses the Answer Tracker
+-----------------------------------
 
 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
@@ -46,7 +48,8 @@ For projects that don't have products, the Answers facet is disabled.
      ...
     zope.testbrowser.browser.LinkNotFoundError
 
-== Browsing Questions ==
+Browsing Questions
+------------------
 
 He realises that support for Kubuntu is probably going on in the Ubuntu
 Answers page and goes there to check.
@@ -143,7 +146,8 @@ details of the question are available.
     [<div class="report"><p>I get really poor hard drive performance.</p></div>]
 
 
-== Jumping to Questions ==
+Jumping to Questions
+--------------------
 
 The Answer Tracker main page permits the user to jump to a question by
 submitting the question's id in the text input field with the 'Find
@@ -188,7 +192,8 @@ is shown search results instead of the question.
     There are no questions matching "question 8" with the requested statuses.
 
 
-== Searching Questions ==
+Searching Questions
+-------------------
 
 Browsing is fine when the number of questions is small, but searching
 is more convenient as the number of questions grow larger.
@@ -250,7 +255,8 @@ error is displayed when the user forgets to select a status.
     You must choose at least one status.
 
 
-== Controlling the Sort Order ==
+Controlling the Sort Order
+--------------------------
 
 That question isn't exactly what Average Joe was looking for. Now, he'd
 like to see all the questions that were related to the firefox package.
@@ -289,12 +295,14 @@ selects the 'oldest first' sort order.
     </table>
 
 
-== Common Reports ==
+Common Reports
+--------------
 
 In the actions menu, we find links to some common reports.
 
 
-=== Open Questions ===
+Open Questions
+..............
 
 Nice Guy likes helping others. He uses the 'Open' link to view the most
 recent questions on Mozilla Firefox.
@@ -329,7 +337,8 @@ problems:
     Problem showing the SVG demo on W3C site
 
 
-=== Answered Questions ===
+Answered Questions
+..................
 
 A random user has a problem with firefox in Ubuntu. They use the
 'Answered' link on the 'Answers' facet of the distribution to look for
@@ -363,7 +372,8 @@ they enter 'Evolution' as a keyword and hit the search button.
     ...
 
 
-=== My questions ===
+My questions
+............
 
 Sample Person remembers posting a question on mozilla-firefox. They use
 the 'My questions' link on the distribution source package Answers facet
@@ -435,7 +445,8 @@ informing them of this fact is displayed.
     You didn't ask any questions about gnomebaker.
 
 
-=== Need attention ===
+Need attention
+..............
 
 A user can often forget which questions need their attention. For
 this purpose, there is a 'Need attention' report which displays the
@@ -488,7 +499,8 @@ informing them of this fact is displayed.
     No questions need your attention for gnomebaker.
 
 
-== Person Reports ==
+Person Reports
+--------------
 
 The Answers facet on on person also contains various searchable
 listings.
@@ -553,7 +565,8 @@ The actions menu contains links to listing that contain only a specific
 type of involvement.
 
 
-=== Assigned ===
+Assigned
+........
 
 The assigned report only lists the questions to which the person is
 assigned.
@@ -565,7 +578,8 @@ assigned.
     No questions assigned to Foo Bar found with the requested statuses.
 
 
-=== Answered ===
+Answered
+........
 
 The 'Answered' link displays all the questions where the person is the
 answerer.
@@ -579,7 +593,8 @@ answerer.
     mailto: problem in webpage
 
 
-=== Commented ===
+Commented
+.........
 
 The report available under the 'Commented' link displays all the
 questions commented on by the person.
@@ -597,7 +612,8 @@ questions commented on by the person.
     Newly installed plug-in doesn't seem to be used
 
 
-=== Asked ===
+Asked
+.....
 
 The 'Asked' link displays a listing containing all the questions
 asked by the person.
@@ -612,7 +628,8 @@ asked by the person.
     Firefox loses focus and gets stuck
 
 
-=== Need attention ===
+Need attention
+..............
 
 The 'Need attention' link displays all the questions that need
 the attention of that person.
@@ -627,7 +644,8 @@ the attention of that person.
     Slow system
 
 
-=== Subscribed ===
+Subscribed
+..........
 
 Foo Bar can find all the questions to which they are subscribed by
 visiting the 'Subscribed' link in the 'Answers' facet.
@@ -641,7 +659,8 @@ visiting the 'Subscribed' link in the 'Answers' facet.
     Slow system
 
 
-== Browsing and Searching Questions in a ProjectGroup ==
+Browsing and Searching Questions in a ProjectGroup
+--------------------------------------------------
 
 When going to the Answers facet of a project, a listing of all the
 questions filed against any of the project's products is displayed.
@@ -699,7 +718,8 @@ The same standard reports than on regular QuestionTarget are available:
     Questions needing your attention for The Mozilla Project : Questions : The Mozilla Project
 
 
-== Searching All Questions ==
+Searching All Questions
+-----------------------
 
 It is possible from the Answer Tracker front page to search among all
 questions ever filed on Launchpad.
@@ -754,7 +774,8 @@ display all questions asked in Launchpad with the selected statuses.
     Firefox cannot render Bank Site             Mozilla Firefox
 
 
-== Searching in a Selected Project ==
+Searching in a Selected Project
+-------------------------------
 
 From the Answers front page, the user can select to search questions
 only in a particular project. In this context a "project" means either
diff --git a/lib/lp/answers/stories/question-compatibility-urls.txt b/lib/lp/answers/stories/question-compatibility-urls.txt
index 29eaf2a..25572d9 100644
--- a/lib/lp/answers/stories/question-compatibility-urls.txt
+++ b/lib/lp/answers/stories/question-compatibility-urls.txt
@@ -1,16 +1,19 @@
-= Backward Compatible URLs =
+Backward Compatible URLs
+========================
 
 The Answer Tracker was renamed from the old Technical Support Tracker.
 As part of that rename many URLs were changed to reflect the new
 terminology. We provide redirect from the old names to the new ones.
 
-== Answer Contact Page ==
+Answer Contact Page
+-------------------
 
     >>> user_browser.open('http://launchpad.test/firefox/+support-contact')
     >>> print(user_browser.url)
     http://answers.launchpad.test/firefox/+answer-contact
 
-== Add Question Page ==
+Add Question Page
+-----------------
 
     >>> user_browser.open('http://launchpad.test/firefox/+addticket')
     >>> print(user_browser.url)
@@ -20,19 +23,22 @@ terminology. We provide redirect from the old names to the new ones.
     >>> print(user_browser.url)
     http://answers.launchpad.test/mozilla/+addquestion
 
-== My Questions Page ==
+My Questions Page
+-----------------
 
     >>> user_browser.open('http://launchpad.test/firefox/+mytickets')
     >>> print(user_browser.url)
     http://answers.launchpad.test/firefox/+myquestions
 
-== Questions Listing ==
+Questions Listing
+-----------------
 
     >>> browser.open('http://launchpad.test/firefox/+tickets')
     >>> print(browser.url)
     http://answers.launchpad.test/firefox/+questions
 
-== Question Page ==
+Question Page
+-------------
 
     >>> browser.open('http://launchpad.test/firefox/+ticket/1')
     >>> print(browser.url)
@@ -42,7 +48,8 @@ terminology. We provide redirect from the old names to the new ones.
     >>> print(browser.url)
     http://api.launchpad.test/devel/firefox/+question/1
 
-== Person Questions Listing ==
+Person Questions Listing
+------------------------
 
     >>> browser.open('http://launchpad.test/~name12/+tickets')
     >>> print(browser.url)
@@ -73,7 +80,8 @@ terminology. We provide redirect from the old names to the new ones.
     http://answers.launchpad.test/~name12/+subscribedquestions
 
 
-== Unsupported questions ==
+Unsupported questions
+---------------------
 
 The Unsupported View is irrelevant. The question search page provides
 links to the +by-language pages that have unsolved questions.
@@ -83,7 +91,8 @@ links to the +by-language pages that have unsolved questions.
     http://answers.launchpad.test/ubuntu/+questions
 
 
-== Enumeration changes in search URLs ==
+Enumeration changes in search URLs
+----------------------------------
 
 The switch from dbschema to lazr based enums changed the values of
 status and sort from titles to uppercase tokens in the search URLs.
diff --git a/lib/lp/answers/stories/question-edit.txt b/lib/lp/answers/stories/question-edit.txt
index be19a95..ef36a05 100644
--- a/lib/lp/answers/stories/question-edit.txt
+++ b/lib/lp/answers/stories/question-edit.txt
@@ -1,4 +1,5 @@
-= Editing Questions =
+Editing Questions
+=================
 
 To edit the title and description of question, one uses the 'Edit
 Question' menu item. You need to be logged in to see the edit form, and
@@ -61,7 +62,8 @@ You can even modify the title and description of 'Answered' and
     <Link...>
 
 
-== Source Package ==
+Source Package
+--------------
 
 Distribution questions can have a source package associated with them.
 Any logged in user can change the question source package on the
@@ -82,7 +84,8 @@ Product questions ignore sourcepackage information if it is submitted:
     >>> user_browser.getControl('Save Changes').click()
 
 
-== Changing Other Metadata ==
+Changing Other Metadata
+-----------------------
 
 A user with 'launchpad.Admin' privilege (usually the product or
 distribution owner) can also change the question Assignee, and
diff --git a/lib/lp/answers/stories/question-message.txt b/lib/lp/answers/stories/question-message.txt
index 0afd96b..50e9a8c 100644
--- a/lib/lp/answers/stories/question-message.txt
+++ b/lib/lp/answers/stories/question-message.txt
@@ -1,4 +1,5 @@
-= Question messages =
+Question messages
+=================
 
 Question messages are plain text. They are formatted as HTML for web
 pages. Many messages originate from emails where unwanted or
@@ -31,7 +32,8 @@ quoted passage, and a signature with an email address in it.
     >>> user_browser.getControl('Add Information Request').click()
 
 
-== Email addresses are only shown to authenticated users ==
+Email addresses are only shown to authenticated users
+-----------------------------------------------------
 
 Email addresses are visible to authenticated users. Sample Person is
 authenticated already, so they will see '[e-mail]'.
@@ -63,7 +65,8 @@ see the obfuscated email address (<email address hidden>).
     Witty signatures rock!
 
 
-== Signatures and quoted passages are hidden ==
+Signatures and quoted passages are hidden
+-----------------------------------------
 
 The style and script in the user_browser control the display and
 behaviour of content inside tags with the class 'foldable'. The script
diff --git a/lib/lp/answers/stories/question-obfuscation.txt b/lib/lp/answers/stories/question-obfuscation.txt
index 87133b1..f6a23c9 100644
--- a/lib/lp/answers/stories/question-obfuscation.txt
+++ b/lib/lp/answers/stories/question-obfuscation.txt
@@ -1,4 +1,5 @@
-= Question obfuscation =
+Question obfuscation
+====================
 
 Launchpad obfuscates email addresses when pages are viewed by
 anonymous users to prevent address harvesting by spammers. Logged
@@ -6,7 +7,8 @@ in users can see the email address in Question descriptions.
 See question-message.txt for additional documentation.
 
 
-== Logged in users can see email addresses ==
+Logged in users can see email addresses
+---------------------------------------
 
 No Privileges Person can see the email address in the tooltip of the
 questions in the Latest questions solved portlet on the Answers
@@ -87,7 +89,8 @@ description. They can then see the email address in the tooltip in the
     ...
 
 
-== Anonymous users cannot see email addresses ==
+Anonymous users cannot see email addresses
+------------------------------------------
 
 Anonymous cannot see the email address anywhere on the Answers front
 page.
diff --git a/lib/lp/answers/stories/question-reject-and-change-status.txt b/lib/lp/answers/stories/question-reject-and-change-status.txt
index ece123c..c7466fd 100644
--- a/lib/lp/answers/stories/question-reject-and-change-status.txt
+++ b/lib/lp/answers/stories/question-reject-and-change-status.txt
@@ -1,4 +1,5 @@
-= Rejecting Questions =
+Rejecting Questions
+===================
 
 Answer contacts and administrators can reject a question.
 This should be done when the question isn't an actual pertinent question
@@ -87,7 +88,8 @@ stating that the question is already rejected:
     ...     print(message.decode_contents())
     The question is already rejected.
 
-= Changing the Question Status =
+Changing the Question Status
+============================
 
 In the previous example, that rejection was clearly a mistake: you
 shouldn't reject a question because it is related to a bug, for these
diff --git a/lib/lp/answers/stories/question-search-multiple-languages.txt b/lib/lp/answers/stories/question-search-multiple-languages.txt
index aaa1ccc..5188300 100644
--- a/lib/lp/answers/stories/question-search-multiple-languages.txt
+++ b/lib/lp/answers/stories/question-search-multiple-languages.txt
@@ -1,4 +1,5 @@
-= Searching Questions in Multiple Languages =
+Searching Questions in Multiple Languages
+=========================================
 
 By default, only questions written in English or one of the user
 preferred languages are listed and searched.
@@ -10,7 +11,8 @@ African IP address, since we'll use that later.
     >>> user_browser.addHeader('X_FORWARDED_FOR', '196.36.161.227')
 
 
-== Anonymous searching ==
+Anonymous searching
+-------------------
 
 For example, a user who isn't logged in will only see questions
 written in English, in one of the language configured in their browser,
@@ -154,7 +156,8 @@ then questions with those language will be displayed:
     Installation failed
 
 
-== Authenticated searching ==
+Authenticated searching
+-----------------------
 
 Authenticated users without preferred languages are assumed to have
 the languages determined by what their browser sends in the
@@ -261,7 +264,8 @@ English, and can use it to locate English questions.
     Slow system
 
 
-== Questions by language ==
+Questions by language
+---------------------
 
 When open questions are in languages that no answer contacts
 speak, the project questions page displays links to see those
@@ -308,7 +312,8 @@ the preceding page.
 The page in all other respects behaves like a question search page.
 
 
-== My questions ignores preferred languages ==
+My questions ignores preferred languages
+----------------------------------------
 
 The "My questions" view ignores the user's language preferences, because
 they may change them over time, but they must always see their questions. For
diff --git a/lib/lp/answers/stories/question-subscriptions.txt b/lib/lp/answers/stories/question-subscriptions.txt
index 3ceaf6a..e4e6b2e 100644
--- a/lib/lp/answers/stories/question-subscriptions.txt
+++ b/lib/lp/answers/stories/question-subscriptions.txt
@@ -1,10 +1,12 @@
-= Question Subscriptions =
+Question Subscriptions
+======================
 
 Users can subscribe to specific questions. When they are subscribed they
 will receive notifications for any changes to the question.
 
 
-== Subscribing ==
+Subscribing
+-----------
 
 To subscribe, users use the 'Subscribe' link and then confirm that
 they want to subscribe by clicking on the 'Subscribe' button. The user
@@ -27,7 +29,8 @@ A message confirming that they were subscribed is displayed:
     You have subscribed to this question.
 
 
-== Unsubscribing ==
+Unsubscribing
+-------------
 
 When the user is subscribed to the question, the 'Subscribe' link
 becomes an 'Unsubscribe' link. To unsubscribe, the user follows that
@@ -49,7 +52,8 @@ A confirmation is displayed:
     You have unsubscribed from this question.
 
 
-== Subscribing While Posting A Message ==
+Subscribing While Posting A Message
+-----------------------------------
 
 It is also possible to subscribe at the same time than posting a message
 on an existing question. The user can simply check the 'Email me future
diff --git a/lib/lp/answers/stories/this-is-a-faq.txt b/lib/lp/answers/stories/this-is-a-faq.txt
index 3164116..ec9e715 100644
--- a/lib/lp/answers/stories/this-is-a-faq.txt
+++ b/lib/lp/answers/stories/this-is-a-faq.txt
@@ -1,4 +1,5 @@
-= Link to a FAQ =
+Link to a FAQ
+=============
 
 Even though similar questions are shown when a user creates a new
 question, common questions still happen for a number of reasons.
@@ -6,7 +7,8 @@ The Answer Tracker can be used to manage common answers
 (a.k.a. Frequently Asked Question - FAQ) which can be used to answer
 a particular question.
 
-== Fix up sample data ==
+Fix up sample data
+------------------
 
 The sample data has question titles which perform poorly with the sample data's
 answers in fulltext searching, using efficient tsearch2 queries; we are going
@@ -23,7 +25,8 @@ permits better matching. See bug 612384.
     >>> logout()
 
 
-== Linking to a FAQ ==
+Linking to a FAQ
+----------------
 
 Any logged in user can use the 'Link to a FAQ' action item to link
 the question to an existing FAQ.
@@ -140,7 +143,8 @@ The answer message was added to the question's discussion:
     FAQ #10: \u201cHow do I install plugins...
 
 
-== Modifying the FAQ ==
+Modifying the FAQ
+-----------------
 
 The link to the FAQ can be changed by using the same 'Link to a FAQ'
 option. Continuing on the previous example, the user went on to read
@@ -193,7 +197,8 @@ The link was also removed from the details portlet:
     Related FAQ: None ...
 
 
-== Creating a new FAQ ==
+Creating a new FAQ
+------------------
 
 When no existing FAQs are relevant, it is possible to create a new FAQ
 from the same 'Link to a FAQ' action. But this option is reserved to
@@ -289,7 +294,8 @@ description:
     Related FAQ: Displaying SVG in Firefox ...
 
 
-== Viewing a FAQ ==
+Viewing a FAQ
+-------------
 
 From a question page which has a related FAQ, the user can click on the
 FAQ title to display the FAQ content.
@@ -328,7 +334,8 @@ the FAQ:
     http://answers.launchpad.test/firefox/+question/2
 
 
-== Distribution and Source Packages ==
+Distribution and Source Packages
+--------------------------------
 
 Questions asked about a distribution or distribution source package
 can also be linked to FAQs.
@@ -351,7 +358,8 @@ can also be linked to FAQs.
     'Is question #8 a FAQ...
 
 
-== Solved questions can be linked to a FAQ ==
+Solved questions can be linked to a FAQ
+---------------------------------------
 
 When linking a solved question to a FAQ the action is treated as a
 comment.
@@ -397,7 +405,8 @@ discussion.
     FAQ #6: ...How can I play MP3/Divx/DVDs/Quicktime/Realmedia files...
 
 
-== FAQs are links ==
+FAQs are links
+--------------
 
 You can respond to a question by pointing people to a FAQ. FAQs are
 linkified as you would expect! You can use the "this is a FAQ" menu
diff --git a/lib/lp/app/doc/displaying-numbers.txt b/lib/lp/app/doc/displaying-numbers.txt
index eb1069b..fcdd4e0 100644
--- a/lib/lp/app/doc/displaying-numbers.txt
+++ b/lib/lp/app/doc/displaying-numbers.txt
@@ -1,8 +1,10 @@
-= Displaying Numbers with ZPT =
+Displaying Numbers with ZPT
+===========================
 
     >>> from lp.testing import test_tales
 
-== bytes: Byte contractions ==
+bytes: Byte contractions
+------------------------
 
 The TALES formatter for numbers allows them to be rendered as byte
 contractions as per IEC60027-2:
@@ -37,7 +39,8 @@ that (thank god!)
     >>> test_tales('foo/fmt:bytes', foo=123456789012345678901234567890)
     '102121.1 YiB'
 
-== float: Float formatting ==
+float: Float formatting
+-----------------------
 
 There's a method that allows formatting float values in TAL analogously
 to how the Python "%f" string formatter works:
diff --git a/lib/lp/app/doc/launchpadform.txt b/lib/lp/app/doc/launchpadform.txt
index e79a5ec..5bf686b 100644
--- a/lib/lp/app/doc/launchpadform.txt
+++ b/lib/lp/app/doc/launchpadform.txt
@@ -1,4 +1,5 @@
-= LaunchpadFormView =
+LaunchpadFormView
+=================
 
 LaunchpadFormView is a base class for form views in Launchpad.  It is
 intended as a replacement for GeneralFormView.
@@ -39,7 +40,8 @@ There is also a LaunchpadEditFormView class to make it easier to write
 edit views.
 
 
-== The Schema ==
+The Schema
+----------
 
 The schema can be an interface implemented by your content object, or
 an interface specifically tailored for data entry.  Below is an
@@ -77,7 +79,8 @@ A form that handles all fields in the schema needs only set the
   ['name', 'displayname', 'password']
 
 
-== Restricting Displayed Fields ==
+Restricting Displayed Fields
+----------------------------
 
 The list of fields can be restricted with the "field_names" attribute:
 
@@ -93,7 +96,8 @@ The list of fields can be restricted with the "field_names" attribute:
   ['name', 'displayname']
 
 
-== Custom Adapters ==
+Custom Adapters
+---------------
 
 Sometimes a schema is used for a form that is not actually implemented
 by the context widget.  This can be handled by providing some custom
@@ -123,7 +127,8 @@ should in turn have the FormTest instance as a context:
   True
 
 
-== Custom Widgets ==
+Custom Widgets
+--------------
 
 In some cases we will want to use a custom widget for a particular
 field.  These can be installed easily with a "custom_widget_NAME"
@@ -150,7 +155,8 @@ attribute:
   <...TextWidget object at ...>
 
 
-== Using Another Context ==
+Using Another Context
+---------------------
 
 setUpWidgets() uses the view's context by default when setting up the
 widgets, but it's also possible to specify the context explicitly.
@@ -167,7 +173,8 @@ widgets, but it's also possible to specify the context explicitly.
   True
 
 
-== Actions ==
+Actions
+-------
 
 In order for a form to accept submissions, it will need one or more
 submit actions.  These are added to the view class using the "action"
@@ -201,7 +208,8 @@ method.  Instead, it should be performed in the validate() method, or
 in per-field validators.
 
 
-== Form Wide Validation ==
+Form Wide Validation
+--------------------
 
 While constraints on individual fields and schema invariants can catch
 the majority of input errors, in some cases it is necessary to
@@ -319,7 +327,8 @@ The default behaviour is to validate all widgets.
   Password: Required input is missing.
 
 
-== Redirect URL ==
+Redirect URL
+------------
 
 If the form is successfully posted, then LaunchpadFormView will
 redirect the user to another URL.  The URL is specified by the
@@ -348,7 +357,8 @@ redirect the user to another URL.  The URL is specified by the
   http://www.ubuntu.com/
 
 
-== Form Rendering ==
+Form Rendering
+--------------
 
   (Let's define the view for the rendering tests.)
   >>> class RenderFormTest(LaunchpadFormView):
@@ -414,7 +424,8 @@ This is also true of failure handlers:
   Some errors occured.
 
 
-== Initial Focused Widget ==
+Initial Focused Widget
+----------------------
 
 The standard template for LaunchpadFormView can set the initial focus
 on a form element.  This is achieved by some javascript that gets run
@@ -461,7 +472,8 @@ error, the generated script will focus the first widget with an error:
   // -->
 
 
-== Hidden widgets ==
+Hidden widgets
+--------------
 
 Any widget can be hidden in a LaunchpadFormView while still having its
 value POSTed with the values of the other (visible) ones. The widget's
@@ -513,7 +525,8 @@ using its hidden() method, which should return a hidden <input> tag.
   >>> os.remove(filename)
 
 
-== Safe Actions ==
+Safe Actions
+------------
 
 By default, LaunchpadFormView requires that form submissions be done
 via POST requests.  There are a number of reasons for this:
@@ -580,7 +593,8 @@ In contrast, the "search" action can be submitted with a GET request:
 
 
 
-== LaunchpadEditFormView ==
+LaunchpadEditFormView
+---------------------
 
 The LaunchpadEditFormView differs from LaunchpadFormView in the
 following ways:
diff --git a/lib/lp/app/doc/tales-email-formatting.txt b/lib/lp/app/doc/tales-email-formatting.txt
index 8c5fc79..0dd70cb 100644
--- a/lib/lp/app/doc/tales-email-formatting.txt
+++ b/lib/lp/app/doc/tales-email-formatting.txt
@@ -1,4 +1,5 @@
-= TALES email formatting =
+TALES email formatting
+======================
 
 There are many edge-cases when marking up email text for presentation.
 There is subtle differences in how people quote text that must be
@@ -12,7 +13,8 @@ First, let's bring in a small helper function:
 
    >>> from lp.testing import test_tales
 
-== Quoting styles ==
+Quoting styles
+--------------
 
 Paragraphs that mix quoted and reply text fold only the quoted lines.
 
@@ -100,7 +102,8 @@ wrapped in a foldable-quoted span.
     </span></p>
 
 
-== Python interpreter and dpkg handling ==
+Python interpreter and dpkg handling
+------------------------------------
 
 The output from the Python interpreter is not quoted text. Passages
 of text that start with '>>> ' are exempted from the 'foldable-quoted'
diff --git a/lib/lp/app/doc/validation.txt b/lib/lp/app/doc/validation.txt
index 7244fe5..3eff615 100644
--- a/lib/lp/app/doc/validation.txt
+++ b/lib/lp/app/doc/validation.txt
@@ -1,6 +1,8 @@
-= Validation =
+Validation
+==========
 
-== LaunchpadValidationError ==
+LaunchpadValidationError
+------------------------
 
 LaunchpadValidationError is the standard exception used for custom
 validators upon a validation error. Rendering one is done by getting
diff --git a/lib/lp/app/stories/basics/marketing.txt b/lib/lp/app/stories/basics/marketing.txt
index 714be3a..eeb08b6 100644
--- a/lib/lp/app/stories/basics/marketing.txt
+++ b/lib/lp/app/stories/basics/marketing.txt
@@ -1,4 +1,5 @@
-= Launchpad tour =
+Launchpad tour
+==============
 
 From Launchpad's front page, you can access the tour.
 
@@ -50,7 +51,8 @@ But the source directory isn't available:
     zope.publisher.interfaces.NotFound: ...
 
 
-== +about compatibility ==
++about compatibility
+--------------------
 
 Each application used to have an introduction living at +about, this is
 now redirected to the relevant tour page.
@@ -80,7 +82,8 @@ now redirected to the relevant tour page.
     http://launchpad.test/+tour/community-support
 
 
-== +tour compatibility ==
++tour compatibility
+-------------------
 
 Similarly, each application has their +tour redirecting to their proper
 tour page.
@@ -110,7 +113,8 @@ tour page.
     http://launchpad.test/+tour/community-support
 
 
-== +faq compatibility ==
++faq compatibility
+------------------
 
 Each application also had a +faq link, that link is also redirected to
 the appropriate tour page.
@@ -136,13 +140,15 @@ the appropriate tour page.
     http://launchpad.test/+tour/community-support
 
 
-== Links to tour on application main page ==
+Links to tour on application main page
+--------------------------------------
 
 Each application home page features a 'Take a tour' button that brings
 the user to the appropriate tour page.
 
 
-=== Code ===
+Code
+....
 
     >>> browser.open('http://code.launchpad.test')
     >>> tour_link = browser.getLink('Take a tour')
@@ -151,7 +157,8 @@ the user to the appropriate tour page.
     >>> tour_link.click()
 
 
-=== Bugs ===
+Bugs
+....
 
     >>> browser.open('http://bugs.launchpad.test')
     >>> tour_link = browser.getLink('take a tour')
@@ -160,7 +167,8 @@ the user to the appropriate tour page.
     >>> tour_link.click()
 
 
-=== Blueprints ===
+Blueprints
+..........
 
     >>> browser.open('http://blueprints.launchpad.test')
     >>> tour_link = browser.getLink('Take a tour')
@@ -169,7 +177,8 @@ the user to the appropriate tour page.
     >>> tour_link.click()
 
 
-=== Translations ===
+Translations
+............
 
     >>> browser.open('http://translations.launchpad.test')
     >>> tour_link = browser.getLink('Take a tour')
@@ -178,7 +187,8 @@ the user to the appropriate tour page.
     >>> tour_link.click()
 
 
-=== Answers ===
+Answers
+.......
 
     >>> browser.open('http://answers.launchpad.test')
     >>> tour_link = browser.getLink('Take a tour')
diff --git a/lib/lp/app/stories/basics/max-batch-size.txt b/lib/lp/app/stories/basics/max-batch-size.txt
index 9bd585b..ce3d44b 100644
--- a/lib/lp/app/stories/basics/max-batch-size.txt
+++ b/lib/lp/app/stories/basics/max-batch-size.txt
@@ -1,4 +1,5 @@
-= Invalid batch size =
+Invalid batch size
+==================
 
 To prevent users from exhausting server resources, pages that use
 batching have a maximum on the batch size. For example, requesting 1000
diff --git a/lib/lp/app/stories/basics/user-requested-oops.txt b/lib/lp/app/stories/basics/user-requested-oops.txt
index d2475a0..0be69d2 100644
--- a/lib/lp/app/stories/basics/user-requested-oops.txt
+++ b/lib/lp/app/stories/basics/user-requested-oops.txt
@@ -1,4 +1,5 @@
-= Requesting an OOPS from Launchpad =
+Requesting an OOPS from Launchpad
+=================================
 
 OOPSes happen from time to time in Launchpad, and they contain lots of
 interesting information for helping debug.  Sometimes though it is useful to
diff --git a/lib/lp/app/stories/basics/xx-dbpolicy.txt b/lib/lp/app/stories/basics/xx-dbpolicy.txt
index 1d42045..433973f 100644
--- a/lib/lp/app/stories/basics/xx-dbpolicy.txt
+++ b/lib/lp/app/stories/basics/xx-dbpolicy.txt
@@ -1,4 +1,5 @@
-= Application Server Database Policy =
+Application Server Database Policy
+==================================
 
 The database policy chooses the default Storm store to used. Its goal
 is to distribute load away from the master databases to read only
diff --git a/lib/lp/app/stories/basics/xx-developerexceptions.txt b/lib/lp/app/stories/basics/xx-developerexceptions.txt
index a8d08b6..ee8c170 100644
--- a/lib/lp/app/stories/basics/xx-developerexceptions.txt
+++ b/lib/lp/app/stories/basics/xx-developerexceptions.txt
@@ -1,4 +1,5 @@
-= Developer exceptions =
+Developer exceptions
+====================
 
 Launchpad developers get tracebacks and a linkified OOPS if an exception
 occurs. Other users get no traceback and only the OOPS ID.
@@ -96,7 +97,8 @@ unregister the adapter.
     >>> error_view_fixture.cleanUp()
 
 
-= http handle_errors =
+http handle_errors
+==================
 
 lp.testing.pages.http accepts the handle_errors parameter in case you
 want to see tracebacks instead of error pages.
diff --git a/lib/lp/app/stories/basics/xx-lowercase-redirection.txt b/lib/lp/app/stories/basics/xx-lowercase-redirection.txt
index 394eda3..b477fe3 100644
--- a/lib/lp/app/stories/basics/xx-lowercase-redirection.txt
+++ b/lib/lp/app/stories/basics/xx-lowercase-redirection.txt
@@ -1,4 +1,5 @@
-= Redirection of Mixed Case paths =
+Redirection of Mixed Case paths
+===============================
 
 When someone visits a page such as http://launchpad.net/jOkOshEr
 launchpad does a permanent redirect to the lowercase path:
diff --git a/lib/lp/app/stories/basics/xx-maintenance-message.txt b/lib/lp/app/stories/basics/xx-maintenance-message.txt
index 51a2a7f..6416bbf 100644
--- a/lib/lp/app/stories/basics/xx-maintenance-message.txt
+++ b/lib/lp/app/stories/basics/xx-maintenance-message.txt
@@ -1,4 +1,5 @@
-= Launchpad maintenance messages =
+Launchpad maintenance messages
+==============================
 
 A system adminstrator can write an iso format timestamp to the file
 "+maintenancetime.txt" in the launchpad application root directory.
@@ -95,7 +96,8 @@ Remove +maintenancetime.txt to clean up.
     >>> os.remove('+maintenancetime.txt')
 
 
-== Per-page maintenance messages ==
+Per-page maintenance messages
+-----------------------------
 
 Alternatively, a maintenance message can be set in the
 app.maintenance_message feature flag, which can be scoped to particular
diff --git a/lib/lp/app/stories/folder.txt b/lib/lp/app/stories/folder.txt
index 8ebd441..8124932 100644
--- a/lib/lp/app/stories/folder.txt
+++ b/lib/lp/app/stories/folder.txt
@@ -1,9 +1,11 @@
-= Serving directories of files =
+Serving directories of files
+============================
 
 LAZR adds special views that can be used to serve all the files under a
 particular directory.
 
-== ExportedFolder ==
+ExportedFolder
+--------------
 
 This is the base implementation. To export a directory, you need to
 subclass that view and provide a folder property returning the path of
@@ -99,7 +101,8 @@ As requesting a non-existent file.
     zope.publisher.interfaces.NotFound: ...
 
 
-== ExportedImageFolder ==
+ExportedImageFolder
+-------------------
 
 For images, it's often convenient not to request the extension. There is
 an ExportedImageFolder subclass, that will accept serving an image file
@@ -140,7 +143,8 @@ If a file without extension exists, that one will be served.
     Image with extension
 
 
-== Exporting trees ==
+Exporting trees
+---------------
 
 By default ExportedFolder doesn't export contained folders, but if the
 export_subdirectories is set to True, it will allow traversing to
@@ -201,7 +205,8 @@ NotFound.
     zope.publisher.interfaces.NotFound: ...
 
 
-== Clean-up ==
+Clean-up
+--------
 
     >>> import shutil
     >>> shutil.rmtree(resource_dir)
diff --git a/lib/lp/app/stories/launchpad-root/xx-featuredprojects.txt b/lib/lp/app/stories/launchpad-root/xx-featuredprojects.txt
index bf0dd16..3f1771a 100644
--- a/lib/lp/app/stories/launchpad-root/xx-featuredprojects.txt
+++ b/lib/lp/app/stories/launchpad-root/xx-featuredprojects.txt
@@ -1,5 +1,6 @@
 
-= Featured Projects =
+Featured Projects
+=================
 
 We maintain a list of featured projects, which are displayed on the home
 page and managed via a special admin-only page.
@@ -7,7 +8,8 @@ page and managed via a special admin-only page.
    >>> MANAGE_LINK = "Manage featured project list"
 
 
-== The home page listing ==
+The home page listing
+---------------------
 
 Featured projects are visible to everyone on the home page. One poject is
 featured as "project of the day" depending on the current day. As we do not
@@ -44,7 +46,8 @@ projects' pages in Launchpad. The "project of the day" is listed separately.
     Mozilla Thunderbird
     Ubuntu
 
-== Adding a featured project ==
+Adding a featured project
+-------------------------
 
 Anonymous users cannot see the link to administer featured projects:
 
@@ -112,7 +115,8 @@ is now at index '4' and is therefore displayed as the top project:
     Mozilla Thunderbird
     Ubuntu
 
-== Removing a project ==
+Removing a project
+------------------
 
     >>> admin_browser.getLink(MANAGE_LINK).click()
     >>> admin_browser.getControl('Apache').click()
diff --git a/lib/lp/app/widgets/doc/announcement-date-widget.txt b/lib/lp/app/widgets/doc/announcement-date-widget.txt
index c6ac676..b33fcaa 100644
--- a/lib/lp/app/widgets/doc/announcement-date-widget.txt
+++ b/lib/lp/app/widgets/doc/announcement-date-widget.txt
@@ -1,4 +1,5 @@
-= AnnouncementDateWidget =
+AnnouncementDateWidget
+======================
 
 This widget combines radio buttons and a DateTimeWidget. It allows you to
 choose to publish an announcement immediately, at a predetermined date in the
diff --git a/lib/lp/app/widgets/doc/lower-case-text-widget.txt b/lib/lp/app/widgets/doc/lower-case-text-widget.txt
index eb84fe1..d9a0237 100644
--- a/lib/lp/app/widgets/doc/lower-case-text-widget.txt
+++ b/lib/lp/app/widgets/doc/lower-case-text-widget.txt
@@ -1,4 +1,5 @@
-= LowerCaseTextWidget =
+LowerCaseTextWidget
+===================
 
 This custom widget is used to convert strings to lower case.
 
diff --git a/lib/lp/app/widgets/doc/noneable-text-widgets.txt b/lib/lp/app/widgets/doc/noneable-text-widgets.txt
index 911a9e3..85ca174 100644
--- a/lib/lp/app/widgets/doc/noneable-text-widgets.txt
+++ b/lib/lp/app/widgets/doc/noneable-text-widgets.txt
@@ -1,10 +1,12 @@
-= Noneable widgets =
+Noneable widgets
+================
 
 In the spirit of Postel's Law, the Noneable widgets permits users to enter
 just whitespace, while ensuring that the schema's field value is None.
 
 
-== Noneable TextLine widget ==
+Noneable TextLine widget
+------------------------
 
 This custom widget is used to normalise the value of meaning less
 text value to None.
@@ -36,7 +38,8 @@ Excess whitespace and newlines are stripped.
     flower
 
 
-== Noneable Description widget ==
+Noneable Description widget
+---------------------------
 
 This custom widget is used to normalise the value of meaning less
 text value to None.
diff --git a/lib/lp/app/widgets/doc/project-scope-widget.txt b/lib/lp/app/widgets/doc/project-scope-widget.txt
index 8816009..e0bf442 100644
--- a/lib/lp/app/widgets/doc/project-scope-widget.txt
+++ b/lib/lp/app/widgets/doc/project-scope-widget.txt
@@ -1,4 +1,5 @@
-= The Project Scope Widget =
+The Project Scope Widget
+========================
 
 Many application front pages contain a search form. The search
 can usually be across the whole Launchpad or only in one project.
@@ -74,7 +75,8 @@ By default, the 'All projects' scope is selected:
       One project:
     ...
 
-== Selecting All Projects ==
+Selecting All Projects
+----------------------
 
 When the 'All projects' option is selected, the widget returns None.
 
@@ -88,7 +90,8 @@ When the 'All projects' option is selected, the widget returns None.
     >>> widget.getInputValue() is None
     True
 
-== Selecting One Project ==
+Selecting One Project
+---------------------
 
 If we select a project, the project with that name is returned
 by getInputValue().
@@ -159,7 +162,8 @@ If no project name is given at all, a widget error is also raised:
     >>> print(widget.error())
     Please enter a project name
 
-== setRenderedValue() ==
+setRenderedValue()
+------------------
 
 In order to initialize the widget with a value, setRenderedValue() is
 used. Passing a product to it will select the 'One project' radio
@@ -197,7 +201,8 @@ Setting the scope to None, will default to the 'All projects' option.
              type="radio" value="all" />
     ...
 
-== getScope() and partial queries ==
+getScope() and partial queries
+------------------------------
 
 In some cases, forms with a ProjectScopeWidget are requested by bots
 which incorrectly build the query string without without the `scope`
diff --git a/lib/lp/app/widgets/doc/tokens-text-widget.txt b/lib/lp/app/widgets/doc/tokens-text-widget.txt
index e51ff15..040b911 100644
--- a/lib/lp/app/widgets/doc/tokens-text-widget.txt
+++ b/lib/lp/app/widgets/doc/tokens-text-widget.txt
@@ -1,4 +1,5 @@
-= Tokens TextLine Widget =
+Tokens TextLine Widget
+======================
 
 This custom widget is used to normalise the space between words,
 strip punctuation, and strip leading and trailing whitespace.
diff --git a/lib/lp/app/widgets/doc/zope3-widgets-use-form-ng.txt b/lib/lp/app/widgets/doc/zope3-widgets-use-form-ng.txt
index 241526d..5888dee 100644
--- a/lib/lp/app/widgets/doc/zope3-widgets-use-form-ng.txt
+++ b/lib/lp/app/widgets/doc/zope3-widgets-use-form-ng.txt
@@ -1,4 +1,5 @@
-= Zope Widgets use IBrowserFormNG =
+Zope Widgets use IBrowserFormNG
+===============================
 
 Regular Zope widgets have the problem of failing with low-level
 exceptions (TypeError, AttributeError, ...) when the request contains
diff --git a/lib/lp/archivepublisher/tests/deathrow.txt b/lib/lp/archivepublisher/tests/deathrow.txt
index 92b4381..4d77654 100644
--- a/lib/lp/archivepublisher/tests/deathrow.txt
+++ b/lib/lp/archivepublisher/tests/deathrow.txt
@@ -1,4 +1,5 @@
-= Package Death Row =
+Package Death Row
+=================
 
 We start by creating a pair of temporary directories to be used in
 this test.
@@ -29,7 +30,8 @@ The no-operation use case, reflects the sampledata status.
     DEBUG Marking 0 condemned packages as removed.
 
 
-== Removal unreferenced packages ==
+Removal unreferenced packages
+-----------------------------
 
 Setup `SoyuzTestPublisher` for creating publications for Ubuntu/hoary.
 
diff --git a/lib/lp/archiveuploader/tests/upload-path-parsing.txt b/lib/lp/archiveuploader/tests/upload-path-parsing.txt
index ea7666e..c4c998d 100644
--- a/lib/lp/archiveuploader/tests/upload-path-parsing.txt
+++ b/lib/lp/archiveuploader/tests/upload-path-parsing.txt
@@ -1,4 +1,5 @@
-= Upload path parsing =
+Upload path parsing
+===================
 
 The upload path is used to decide in which context a uploaded package
 will be processed.
@@ -19,7 +20,8 @@ in several scenarios.
     ...     print('Suite: %s' % suite_name)
 
 
-== Distribution uploads ==
+Distribution uploads
+--------------------
 
 Upload placed on 'root', i.e, no 'relative_path' will be targeted to
 'ubuntu' primary archive.
@@ -74,7 +76,8 @@ is raised.
     lp.archiveuploader.uploadprocessor.UploadPathError: Could not find suite 'imaginary'.
 
 
-== PPA uploads ==
+PPA uploads
+-----------
 
 An upload will be considered targeted to a PPA if the first path term
 starts with '~', then the subsequent text in this term will be looked
@@ -204,7 +207,8 @@ And the upload now found its way to the new named PPA.
     Suite: None
 
 
-== Non-sense upload paths ==
+Non-sense upload paths
+----------------------
 
 Obviously upload paths can be completely bogus and the processing function
 identifies and warns users accordingly.
@@ -259,7 +263,8 @@ An old-style named PPA upload missing '~'.
     lp.archiveuploader.uploadprocessor.UploadPathError: Path format mismatch.
 
 
-== Binary uploads from build slaves ==
+Binary uploads from build slaves
+--------------------------------
 
 A relative path for a binary upload from a build slave will have the
 following format: <archive_id>/<distribution_name> where archive_id
diff --git a/lib/lp/blueprints/stories/blueprints/xx-buglinks.txt b/lib/lp/blueprints/stories/blueprints/xx-buglinks.txt
index 6c4e692..04ea753 100644
--- a/lib/lp/blueprints/stories/blueprints/xx-buglinks.txt
+++ b/lib/lp/blueprints/stories/blueprints/xx-buglinks.txt
@@ -1,4 +1,5 @@
-= Linking Specs and Bugs =
+Linking Specs and Bugs
+======================
 
 Specifications can be linked to bugs. Bug reports exposing problems that
 will be solved by the specification are likely candidates for such
@@ -16,7 +17,8 @@ the 'Related Bugs' section.
     Bug #1: Firefox does not support SVG   New
 
 
-== Adding Links ==
+Adding Links
+------------
 
 Linking a bug report to a specification is done by using the
 'Link to a bug report' link.
@@ -46,7 +48,8 @@ link.
     ...Reflow problems with complex page layouts...</div>
 
 
-== Removing Links ==
+Removing Links
+--------------
 
 Oops, that was actually the wrong bug. So lets remove the link. This is
 done by using the 'Remove bug link' link.
diff --git a/lib/lp/blueprints/stories/blueprints/xx-dependencies.txt b/lib/lp/blueprints/stories/blueprints/xx-dependencies.txt
index 9b66034..9021466 100644
--- a/lib/lp/blueprints/stories/blueprints/xx-dependencies.txt
+++ b/lib/lp/blueprints/stories/blueprints/xx-dependencies.txt
@@ -1,4 +1,5 @@
-= Blueprint dependencies =
+Blueprint dependencies
+======================
 
 Blueprints support the idea of dependencies: one blueprint can require
 another blueprint be complete before its own implementation can
@@ -18,7 +19,8 @@ itself.
   True
 
 
-== Adding a new dependency ==
+Adding a new dependency
+-----------------------
 
 Let's add a new dependency for the "canvas" blueprint. We'll add the
 "extension-manager-upgrades" blueprint as a dependency. First, we
@@ -67,7 +69,8 @@ dependency.
   'http://blueprints.launchpad.test/firefox/+spec/canvas'
 
 
-== Removing a dependency ==
+Removing a dependency
+---------------------
 
 But we don't want to keep that, so we will remove it as a dependency. First
 we make sure we can see the link to remove a dependency. We need to be
@@ -122,9 +125,11 @@ users with launchpad.Edit permission for the blueprint.
   zope.security.interfaces.Unauthorized: ...
 
 
-== Corner cases ==
+Corner cases
+------------
 
-=== Cross-project blueprints ===
+Cross-project blueprints
+........................
 
 Blueprints can only depend on blueprints in the same project. To
 show this, we register a blueprint for a different project.
@@ -152,7 +157,8 @@ blueprint we registered in jokosher.
   True
 
 
-=== Circular dependencies ===
+Circular dependencies
+.....................
 
 In order to prevent circular dependencies, it is impossible to mark a
 blueprint A as depending on blueprint B, if B is already marked as
@@ -170,7 +176,8 @@ We know that "canvas" depends on "e4x". We try to make "e4x" depend on
   True
 
 
-=== Status ===
+Status
+......
 
 It should be possible to indicate any blueprint as a dependency,
 regardless of its status. Let's mark mergewin as Implemented:
@@ -196,7 +203,8 @@ And ensure it works:
   'http://blueprints.launchpad.test/firefox/+spec/canvas'
 
 
-== Project dependency charts ==
+Project dependency charts
+-------------------------
 
 We know that no blueprints depend on "canvas", but "canvas" depends on
 "e4x" and "e4x" depends on "svg-support". So the big picture is that
@@ -256,7 +264,8 @@ is useful for experimenting with the dot layout using production data.
   digraph "deptree" {
   ...
 
-== Distro blueprints ==
+Distro blueprints
+-----------------
 
 Let's look at blueprints targetting a distribution, rather than a product.
 We create two blueprints in `ubuntu`.
diff --git a/lib/lp/blueprints/stories/standalone/xx-batching.txt b/lib/lp/blueprints/stories/standalone/xx-batching.txt
index 0c3ca4c..619b246 100644
--- a/lib/lp/blueprints/stories/standalone/xx-batching.txt
+++ b/lib/lp/blueprints/stories/standalone/xx-batching.txt
@@ -1,4 +1,5 @@
-= Blueprint Batching =
+Blueprint Batching
+==================
 
 For projects with large numbers of blueprints, it's important that users are
 able to navigate easily through those blueprints. It's also important for us 
diff --git a/lib/lp/blueprints/stories/standalone/xx-informational-blueprints.txt b/lib/lp/blueprints/stories/standalone/xx-informational-blueprints.txt
index e2d67f8..0603ab6 100644
--- a/lib/lp/blueprints/stories/standalone/xx-informational-blueprints.txt
+++ b/lib/lp/blueprints/stories/standalone/xx-informational-blueprints.txt
@@ -1,4 +1,5 @@
-= Informational Blueprints =
+Informational Blueprints
+========================
 
 Informational blueprints are blueprints for which no implementation is
 necessary, other than writing the blueprint itself. We track such blueprints
@@ -6,7 +7,8 @@ by setting their ''implementation_status'' to ''informational'' and using
 only their ''definition_status'' to follow change.
 
 
-== Tracking informational blueprints ==
+Tracking informational blueprints
+---------------------------------
 
 When a blueprint does not require an implementation at all, it can be
 said to be ''informational'', and it isn't necessary to track its
@@ -38,7 +40,8 @@ The blueprint is displayed with the ''informational'' icon.
     <...Informational blueprint, no implementation necessary...>
 
 
-== Documentation ==
+Documentation
+-------------
 
 An informational blueprint that has been approved, displays on the its
 project's documentation page.
diff --git a/lib/lp/bugs/browser/tests/buglinktarget-views.txt b/lib/lp/bugs/browser/tests/buglinktarget-views.txt
index 192d936..ed48965 100644
--- a/lib/lp/bugs/browser/tests/buglinktarget-views.txt
+++ b/lib/lp/bugs/browser/tests/buglinktarget-views.txt
@@ -1,4 +1,5 @@
-= IBugLinkTarget Views =
+IBugLinkTarget Views
+====================
 
 The +linkbug and +unlinkbug views operates on IBugLinkTarget.
 
@@ -24,7 +25,8 @@ The +linkbug and +unlinkbug views operates on IBugLinkTarget.
     >>> login('[e-mail]')
 
 
-== Link Bug View ==
+Link Bug View
+-------------
 
 The +linkbug view is used to link bugs to IBugLinkTarget.
 
@@ -72,7 +74,8 @@ A ObjectModifiedEvent was sent:
     >>> collected_events = []
 
 
-== Unlink Bugs View ==
+Unlink Bugs View
+----------------
 
     (Link some other bugs first.)
     >>> link = cve.linkBug(bugset.get(2))
@@ -122,7 +125,8 @@ A ObjectModifiedEvent was sent:
     [1, 2, 3]
 
 
-== Bug titles are escaped in notifications ==
+Bug titles are escaped in notifications
+---------------------------------------
 
 Bug titles may legitimately contain HTML markup, such as reporting that
 there is "Too much space between <h1> and <h2>". Notifications, like the
@@ -149,7 +153,8 @@ The notification contains the escaped bug title.
     ...&lt;script&gt;window.alert(&quot;Hello!&quot;)&lt;/script&gt;....
 
 
-== Cleanup ==
+Cleanup
+-------
 
     (Deactivate the event listener.)
     >>> modified_listener.cleanUp()
diff --git a/lib/lp/bugs/browser/tests/bugtask-edit-views.txt b/lib/lp/bugs/browser/tests/bugtask-edit-views.txt
index 1896e5e..6dfeb04 100644
--- a/lib/lp/bugs/browser/tests/bugtask-edit-views.txt
+++ b/lib/lp/bugs/browser/tests/bugtask-edit-views.txt
@@ -1,10 +1,12 @@
-= Editing Bug Tasks =
+Editing Bug Tasks
+=================
 
 A bugtask's status, assignee, package name, milestone, etc., can be
 modified on its +editstatus page.
 
 
-== Edit the Status ==
+Edit the Status
+---------------
 
 Let's start simple and edit the status of a bug task logged in as Sample
 Person:
@@ -33,7 +35,8 @@ Person:
     'In Progress'
 
 
-== Edit the Package ==
+Edit the Package
+----------------
 
 When editing the package of a distribution task, the user may enter
 either a binary or a source package name. We only deal with bugs on
@@ -91,7 +94,8 @@ exist in Launchpad. we'll get an error message.
 An error is reported to the user when a bug is retargeted and there is
 an existing task for the same target.
 
-== Edit the Product ==
+Edit the Product
+----------------
 
 +editstatus allows a bug to be retargeted to another product.
 
@@ -141,7 +145,8 @@ If no product name is given, an error message is displayed.
     ('product', 'Project', RequiredMissing('product'))
 
 
-== Bug Watch Linkage ==
+Bug Watch Linkage
+-----------------
 
 Let's edit a bugtask which is linked to a remote bug. The most
 important thing to edit is the bug watch, since it controls the status
@@ -204,7 +209,8 @@ set to their default values:
     True
 
 
-== Milestone Editing Permissions ==
+Milestone Editing Permissions
+-----------------------------
 
 A milestone can be edited only by a user with launchpad.Edit permissions
 on the distribution or product context. When the user has this
diff --git a/lib/lp/bugs/browser/tests/bugtask-search-views.txt b/lib/lp/bugs/browser/tests/bugtask-search-views.txt
index 97120cc..041a1fa 100644
--- a/lib/lp/bugs/browser/tests/bugtask-search-views.txt
+++ b/lib/lp/bugs/browser/tests/bugtask-search-views.txt
@@ -1,4 +1,5 @@
-= Distribution Search page =
+Distribution Search page
+========================
 
 In the 'Bugs' facet of a distribution we can find a list of bugs
 reported in that distribution and simple and advanced search forms.
@@ -208,7 +209,8 @@ in each series. In this case, the component search widget is hidden.
     False
 
 
-== Distribution Series search page ==
+Distribution Series search page
+-------------------------------
 
     >>> sarge = debian.getSeries('sarge')
 
@@ -286,7 +288,8 @@ The same is true for a sarge package.
     []
 
 
-== ProjectGroup Search Page ==
+ProjectGroup Search Page
+------------------------
 
     >>> from lp.registry.interfaces.projectgroup import IProjectGroupSet
     >>> mozilla = getUtility(IProjectGroupSet).getByName('mozilla')
@@ -353,7 +356,8 @@ Check what milestones are displayed on the advanced search form:
     Mozilla Firefox 1.0 (2056-10-16)
 
 
-== Searching by information type ==
+Searching by information type
+-----------------------------
 
 The advanced form allows us to query for bugs matching specific
 information types.
@@ -390,7 +394,8 @@ Submit the search:
     >>> flush_database_updates()
 
 
-== Constructing search filter urls ==
+Constructing search filter urls
+-------------------------------
 
 There is a helper method, get_buglisting_search_filter_url(), which can
 be used to construct bug search URLs. It takes keyword parameters for
diff --git a/lib/lp/bugs/browser/tests/distrosourcepackage-bug-views.txt b/lib/lp/bugs/browser/tests/distrosourcepackage-bug-views.txt
index 48620d1..c3a85c2 100644
--- a/lib/lp/bugs/browser/tests/distrosourcepackage-bug-views.txt
+++ b/lib/lp/bugs/browser/tests/distrosourcepackage-bug-views.txt
@@ -1,6 +1,8 @@
-= Distro Source Package Bug Views =
+Distro Source Package Bug Views
+===============================
 
-== Searching ==
+Searching
+---------
 
 Simple searching is possible on the distro source package bug view page.
 
diff --git a/lib/lp/bugs/doc/bug-change.txt b/lib/lp/bugs/doc/bug-change.txt
index f2e2170..f51c352 100644
--- a/lib/lp/bugs/doc/bug-change.txt
+++ b/lib/lp/bugs/doc/bug-change.txt
@@ -1,4 +1,5 @@
-= Tracking changes to a bug =
+Tracking changes to a bug
+=========================
 
 The base class for BugChanges doesn't actually implement anything.
 
@@ -190,9 +191,11 @@ notification you'll get an error.
     AssertionError: notification_data must include a `text` value.
 
 
-== BugChange subclasses ==
+BugChange subclasses
+--------------------
 
-=== Getting the right bug change class ===
+Getting the right bug change class
+..................................
 
 Given that we know what's changing and the name of the field that is
 being changed, we can find a suitable IBugChange implementation to
@@ -221,7 +224,8 @@ get_bug_change_class will also work for BugTasks.
     <class '...BugTaskImportanceChange'>
 
 
-=== AttributeChange ===
+AttributeChange
+...............
 
 The AttributeChange class offers basic functionality for dealing with
 bug attribute changes.
@@ -244,7 +248,8 @@ method.
      'whatchanged': 'title'}
 
 
-=== BugDescriptionChange ===
+BugDescriptionChange
+....................
 
 This describes a change to the description of a
 bug. getBugNotification() returns a formatted description of the
@@ -264,7 +269,8 @@ change.
     + Well, maybe not
 
 
-=== BugTitleChange ===
+BugTitleChange
+..............
 
 This, surprisingly, describes a title change for a bug. Again,
 getBugNotification() returns a specially formatted description of
@@ -291,7 +297,8 @@ within the UI.
     summary
 
 
-=== BugDuplicateChange ===
+BugDuplicateChange
+..................
 
 This describes a change to the duplicate marker for a bug.
 
@@ -316,7 +323,8 @@ returned fields.
      'whatchanged': 'marked as duplicate'}
 
 
-== BugTagsChange ==
+BugTagsChange
+-------------
 
 BugTagsChange is used to represent a change in a Bug's tag list.
 
@@ -345,7 +353,8 @@ Addtions and removals are expressed separately in the notification.
     ** Tags added: zillionth-tag
 
 
-=== CveLinkedToBug / CveUnlinkedFromBug ===
+CveLinkedToBug / CveUnlinkedFromBug
+...................................
 
 These describe the linking or unlinking of a CVE to a bug.
 
@@ -381,7 +390,8 @@ And when a CVE is unlinked from a bug.
     ** CVE removed: https://cve.mitre.org/cgi-bin/cvename.cgi?name=1999-8979
 
 
-== BugAttachmentChange ==
+BugAttachmentChange
+-------------------
 
 BugAttachmentChange is used to handle the addition and removal of
 attachments from a bug.
@@ -426,7 +436,8 @@ Or remove one.
     http://bugs.launchpad.test/bugs/.../+attachment/.../+files/...
 
 
-== BugTaskAttributeChange ==
+BugTaskAttributeChange
+----------------------
 
 BugTaskAttributeChange is a generic BugChange that can be used to
 represent a change in the attributes of one of a Bug's BugTasks. It is
@@ -467,7 +478,8 @@ Several types of attribute change can be handled by
 BugTaskAttributeChange.
 
 
-=== Status changes ===
+Status changes
+..............
 
 Status changes use a BugTaskStatus's `title` attribute to describe to
 the user what has changed.
@@ -490,7 +502,8 @@ the user what has changed.
            Status: New => Fix Released
 
 
-=== Importance changes ===
+Importance changes
+..................
 
 Importance changes use a BugTaskImportance's `title` attribute to
 describe to the user what has changed.
@@ -514,7 +527,8 @@ describe to the user what has changed.
        Importance: Undecided => Critical
 
 
-=== Milestone changes ===
+Milestone changes
+.................
 
 Milestone changes use a Milestone's `name` attribute to describe to
 the user what has changed.
@@ -541,7 +555,8 @@ the user what has changed.
         Milestone: None => example-milestone
 
 
-=== Bugwatch changes ===
+Bugwatch changes
+................
 
 Bugwatch changes use a Bugwatch's `title` attribute to describe to the
 user what has changed.
@@ -570,7 +585,8 @@ user what has changed.
      Remote watch: None => bugs.example.com/ #1245
 
 
-=== Assignee changes ===
+Assignee changes
+................
 
 Assignee changes use the assignee's `unique_displayname` attribute to
 describe to the user what has changed.
@@ -593,7 +609,8 @@ describe to the user what has changed.
          Assignee: (unassigned) => Ford Prefect (ford-prefect)
 
 
-=== Target (Affects) changes ===
+Target (Affects) changes
+........................
 
 Changes to the bug task target (aka affects) use the BugTaskTargetChange
 class to describe the change. It inspects the `bugtargetname`
diff --git a/lib/lp/bugs/doc/bug-reported-acknowledgement.txt b/lib/lp/bugs/doc/bug-reported-acknowledgement.txt
index 6997fa4..393b23b 100644
--- a/lib/lp/bugs/doc/bug-reported-acknowledgement.txt
+++ b/lib/lp/bugs/doc/bug-reported-acknowledgement.txt
@@ -1,4 +1,5 @@
-= Bug Reported Acknowledgement Message =
+Bug Reported Acknowledgement Message
+====================================
 
 A message of acknowledgement to be displayed to bug reporters after they've
 reported a bug can be set at the Distribution, DistributionSourcePackage,
diff --git a/lib/lp/bugs/doc/bug-reporting-guidelines.txt b/lib/lp/bugs/doc/bug-reporting-guidelines.txt
index b6ebff5..44cb6c4 100644
--- a/lib/lp/bugs/doc/bug-reporting-guidelines.txt
+++ b/lib/lp/bugs/doc/bug-reporting-guidelines.txt
@@ -1,4 +1,5 @@
-= Bug Reporting Guidelines =
+Bug Reporting Guidelines
+========================
 
 Guidelines can be set at the Distribution, DistributionSourcePackage,
 ProjectGroup or Product level to help users file good bug reports, direct
diff --git a/lib/lp/bugs/doc/bug-set-status.txt b/lib/lp/bugs/doc/bug-set-status.txt
index af6cd66..89caa02 100644
--- a/lib/lp/bugs/doc/bug-set-status.txt
+++ b/lib/lp/bugs/doc/bug-set-status.txt
@@ -1,4 +1,5 @@
-= Setting the status of a bug =
+Setting the status of a bug
+===========================
 
 If you have a bug and a target, there's method which makes it easier to
 change the bug's status for that specific target. It expects the user
@@ -67,7 +68,8 @@ bugtask already has the specified status, None is returned.
     >>> print(bug.setStatus(firefox, BugTaskStatus.CONFIRMED, no_priv))
     None
 
-=== Product series ===
+Product series
+..............
 
 If a product series is specified, but the bug is target only to the
 product, not the product series, the product bugtask is edited.
@@ -126,7 +128,8 @@ updated automatically.
     >>> firefox_bugtask.status.name
     'CONFIRMED'
 
-=== Distributions and packages ===
+Distributions and packages
+..........................
 
 Setting the status of a distribution or package bugtask work the same as
 for product tasks.
diff --git a/lib/lp/bugs/doc/bugmessage-visibility.txt b/lib/lp/bugs/doc/bugmessage-visibility.txt
index 0c91cfb..43c683e 100644
--- a/lib/lp/bugs/doc/bugmessage-visibility.txt
+++ b/lib/lp/bugs/doc/bugmessage-visibility.txt
@@ -1,4 +1,5 @@
-= Bug message visibility =
+Bug message visibility
+======================
 
 Bug messages have a visible field, which provides a means
 for hiding messages rather than having to delete them.
diff --git a/lib/lp/bugs/doc/bugmessage.txt b/lib/lp/bugs/doc/bugmessage.txt
index 9e14348..34c4e7f 100644
--- a/lib/lp/bugs/doc/bugmessage.txt
+++ b/lib/lp/bugs/doc/bugmessage.txt
@@ -1,4 +1,5 @@
-= Bug Messages =
+Bug Messages
+============
 
 Bug messages are messages associated with bugs. A bug message is
 described by the IBugMessage interface.
@@ -6,7 +7,8 @@ described by the IBugMessage interface.
 One IMessage can be associated with many IBugs, but one IBugMessage is
 always associated with exactly one bug.
 
-== Retrieving bug messages ==
+Retrieving bug messages
+-----------------------
 
 IBugMessageSet represents the set of all IBugMessages in the
 system.
@@ -47,7 +49,8 @@ bug watch.
     ...
 
 
-== Creating bug messages ==
+Creating bug messages
+---------------------
 
 To create a bug message, use IBugMessageSet.createMessage:
 
@@ -74,7 +77,8 @@ And the index of the bugmessage is set:
     2
 
 
-== Links and CVEs in bug messages ==
+Links and CVEs in bug messages
+------------------------------
 
 If a bug message contains links to an external bug report or a CVE,
 bugwatches resp. CVE watches are automatically created. We add this
@@ -156,7 +160,8 @@ an external bug tracker.
     http://some.bugzilla/show_bug.cgi?id=9876
 
 
-== Last message date ==
+Last message date
+-----------------
 
 For each bug, we cache the date of the last message linked to it using
 the attribute `date_last_message` in order to optimize searches the need
@@ -174,7 +179,8 @@ to compare this value for every bug in a large set.
     True
 
 
-== Retrieving IMessage.id from IBugMessage ==
+Retrieving IMessage.id from IBugMessage
+---------------------------------------
 
 Each IBugMessage has a message_id attribute, which allows access
 to IBugMessage.IMessage.id without the additional query.
diff --git a/lib/lp/bugs/doc/bugnotifications.txt b/lib/lp/bugs/doc/bugnotifications.txt
index 1e364cc..d4ea291 100644
--- a/lib/lp/bugs/doc/bugnotifications.txt
+++ b/lib/lp/bugs/doc/bugnotifications.txt
@@ -1,15 +1,18 @@
 
-= Bug notifications =
+Bug notifications
+=================
 
 
-== What is a bug notification? ==
+What is a bug notification?
+---------------------------
 
 A bug notification gets added when something interesting happens to the
 bug. It's stored in a a table, and later on a cronscript constructs an
 email and sends the notification to the bug's subscribers.
 
 
-== When do bug notifications get added? ==
+When do bug notifications get added?
+------------------------------------
 
 Not *every* change on a bug causes a notification to be added. This
 section will give a rundown of the things that do cause notifications to
@@ -21,7 +24,8 @@ Here are the things that cause bug notifications to be added and what
 those notifications look like.
 
 
-=== Reporting a new bug ===
+Reporting a new bug
+...................
 
     >>> from zope.event import notify
     >>> from lazr.lifecycle.event import ObjectCreatedEvent
@@ -63,7 +67,8 @@ bugactivity.txt, but for now here is a small demo.
     Sample Person
 
 
-=== Editing a bug report ===
+Editing a bug report
+....................
 
     >>> from lp.services.webapp.snapshot import notify_modified
 
@@ -88,7 +93,8 @@ bugactivity.txt, but for now here is a small demo.
     a new description
 
 
-=== Filing a new task on an existing bug ===
+Filing a new task on an existing bug
+....................................
 
 There are three kinds of tasks that can be added to an existing
 bug. Let's take a look at each type.
@@ -201,7 +207,8 @@ bug. Let's take a look at each type.
     ...
 
 
-=== Commenting on a bug report ===
+Commenting on a bug report
+..........................
 
     >>> from lp.bugs.interfaces.bugmessage import IBugMessageSet
 
@@ -223,7 +230,8 @@ bug. Let's take a look at each type.
     just a test comment
 
 
-=== Editing a task ===
+Editing a task
+..............
 
 Let's demonstrate a notification email where Sample Person marks a
 task Fixed, and assigns themselves to it.
@@ -265,7 +273,8 @@ task Fixed, and assigns themselves to it.
     ...
 
 
-=== Adding and editing a CVE reference ===
+Adding and editing a CVE reference
+..................................
 
 Adding a CVE reference to a bug also causes a notification email to go
 out to the bug notification recipient list. Let's create a CVE ref and
@@ -290,7 +299,8 @@ this document:
     ** CVE added: https://cve.mitre.org/cgi-bin/cvename.cgi?name=2004-0276
 
 
-=== Expiring notifications ===
+Expiring notifications
+......................
 
 During bulk imports or changes of bugs, we often want to suppress
 email notifications.  Due to the previous operation, there is a
diff --git a/lib/lp/bugs/doc/bugtarget.txt b/lib/lp/bugs/doc/bugtarget.txt
index 9fa9f2d..59a60fd 100644
--- a/lib/lp/bugs/doc/bugtarget.txt
+++ b/lib/lp/bugs/doc/bugtarget.txt
@@ -1,10 +1,12 @@
-= Bug Targets =
+Bug Targets
+===========
 
 A bug target is a thing on which a bug can be reported, e.g., an
 IDistributionSourcePackage, an IProduct, etc.
 
 
-== Bug Tasks on Bug Targets ==
+Bug Tasks on Bug Targets
+------------------------
 
 Bug targets have a bugtargetdisplayname attribute, which returns a value
 tailored for human reading (e.g. display in Web pages); and a bugtargetname
diff --git a/lib/lp/bugs/doc/bugtask-package-bugcounts.txt b/lib/lp/bugs/doc/bugtask-package-bugcounts.txt
index 60af96d..7d24bfc 100644
--- a/lib/lp/bugs/doc/bugtask-package-bugcounts.txt
+++ b/lib/lp/bugs/doc/bugtask-package-bugcounts.txt
@@ -1,4 +1,5 @@
-= Bug Counts For Open Bugs on Packages =
+Bug Counts For Open Bugs on Packages
+====================================
 
 BugTaskset has a method, getBugCountsForPackages(), which returns counts
 for open bugs on each package.
@@ -128,7 +129,8 @@ If we mark the bug as In Progress, the open_inprogress will increase.
     open_unassigned: 1
     package: mozilla-firefox (Ubuntu)
 
-== Privacy ==
+Privacy
+-------
 
 Only those bugs that the user has access to are shown, so if we mark the
 bug as private, No Privileges Person will only see that there is one
@@ -160,7 +162,8 @@ Foo Bar still can see all the bugs, though.
     open_unassigned: 1
     package: mozilla-firefox (Ubuntu)
 
-== Duplicate Bugs ==
+Duplicate Bugs
+--------------
 
 Duplicates bugs are omitted from the counts.
 
diff --git a/lib/lp/bugs/doc/bugtask-search-old-urls.txt b/lib/lp/bugs/doc/bugtask-search-old-urls.txt
index 388be56..34a6b7b 100644
--- a/lib/lp/bugs/doc/bugtask-search-old-urls.txt
+++ b/lib/lp/bugs/doc/bugtask-search-old-urls.txt
@@ -1,4 +1,5 @@
-= Searching bugtasks with old statuses =
+Searching bugtasks with old statuses
+====================================
 
 The BugWorkflow spec renames several bug statuses, but we need
 bookmarks, etc., to keep working using the old status names. Instead
diff --git a/lib/lp/bugs/doc/bugtask-status-workflow.txt b/lib/lp/bugs/doc/bugtask-status-workflow.txt
index 3363180..2ffd3be 100644
--- a/lib/lp/bugs/doc/bugtask-status-workflow.txt
+++ b/lib/lp/bugs/doc/bugtask-status-workflow.txt
@@ -1,4 +1,5 @@
-= BugTask Status Workflow =
+BugTask Status Workflow
+=======================
 
 BugTasks have a natural status workflow: New => Confirmed => In
 Progress => Fix Committed => Fix Released, etc. Some state transitions
@@ -301,7 +302,8 @@ setting an assignee has "side effects".
     True
 
 
-== date_xxx and the UNKNOWN status ==
+date_xxx and the UNKNOWN status
+-------------------------------
 
 When an IBugTask is set to status UNKNOWN, the date_confirmed,
 date_closed, date_inprogress, date_triaged, date_fixcommitted
diff --git a/lib/lp/bugs/doc/bugwidget.txt b/lib/lp/bugs/doc/bugwidget.txt
index 680bf16..f20d44a 100644
--- a/lib/lp/bugs/doc/bugwidget.txt
+++ b/lib/lp/bugs/doc/bugwidget.txt
@@ -1,4 +1,5 @@
-= Widget for entering a bug id =
+Widget for entering a bug id
+============================
 
 The BugWidget converts string bug ids to the corresponding bug object.
 
diff --git a/lib/lp/bugs/doc/cve.txt b/lib/lp/bugs/doc/cve.txt
index 631cd55..6801d8f 100644
--- a/lib/lp/bugs/doc/cve.txt
+++ b/lib/lp/bugs/doc/cve.txt
@@ -1,4 +1,5 @@
-= Common Vulnerabilities and Exposures (CVE) =
+Common Vulnerabilities and Exposures (CVE)
+==========================================
 
 Malone supports attaching CVE references to bugs. From
 https://cve.mitre.org/about/ CVE is:
@@ -11,11 +12,13 @@ For more information, consult the CVE website:
 
     https://cve.mitre.org/
 
-== CveSet ==
+CveSet
+------
 
 The ICveSet utility is used to create and get CVEs and BugCves.
 
-=== Creating CVE entries ===
+Creating CVE entries
+....................
 
 CVE references can be created with the ICveSet utility.
 
@@ -35,7 +38,8 @@ To create a CVE, call ICveSet.new(sequence, description,
     >>> print(cve.displayname)
     CVE-2004-0276
 
-=== Number of CVE links ===
+Number of CVE links
+...................
 
 We can get the number of CVE links to bugs in Launchpad using
 getBugCveCount.
@@ -62,7 +66,8 @@ And if we unlink it, the count will decrease.
     >>> cveset.getBugCveCount()
     2
 
-== Linking CVEs to Bugs ==
+Linking CVEs to Bugs
+--------------------
 
 You can link a CVE to a bug. You can also see which CVEs are currently
 linked to a bug:
@@ -139,7 +144,8 @@ Text references to CVEs using 2014 format can be found:
     True
     >>> b.unlinkCVE(cve_2014, user=no_priv)
 
-== CVE Reports ==
+CVE Reports
+-----------
 
 Launchpad offers distributions, distribution releases and products with
 reports that inform on the status of bugs related to CVEs in the
diff --git a/lib/lp/bugs/doc/displaying-bugs-and-tasks.txt b/lib/lp/bugs/doc/displaying-bugs-and-tasks.txt
index 25f9674..3e4af4f 100644
--- a/lib/lp/bugs/doc/displaying-bugs-and-tasks.txt
+++ b/lib/lp/bugs/doc/displaying-bugs-and-tasks.txt
@@ -1,11 +1,13 @@
-= Displaying Information on Bugs and Bug Tasks =
+Displaying Information on Bugs and Bug Tasks
+============================================
 
 This document discusses TALES techniques and IBugTask object
 attributes that may be useful to you, if you're writing some code to
 display bug and bug task information.
 
 
-== Displaying an Icon with image:icon ==
+Displaying an Icon with image:icon
+----------------------------------
 
 image:sprite_css is a TALES adapter that returns the CSS class for
 an icon for a bugtask.
@@ -60,7 +62,8 @@ Let's use a few examples to demonstrate:
   ...   ORIGINAL_IMPORTANCE, getUtility(ILaunchBag).user)
 
 
-== Displaying Logos for Bug Tasks ==
+Displaying Logos for Bug Tasks
+------------------------------
 
 The logo for a bug task display the corresponding logo for its
 target.
@@ -85,7 +88,8 @@ And the logo for a distro bug task shows the source package icon:
   '<img alt="" width="64" height="64" src="/@@/distribution-logo" />'
 
 
-== Displaying Status ==
+Displaying Status
+-----------------
 
 Sometimes it's useful to display the status of an IBugTask as a
 human-readable string. So, instead of displaying something like:
@@ -157,7 +161,8 @@ Lastly, some cleanup:
   >>> test_task.transitionToAssignee(ORIGINAL_ASSIGNEE)
 
 
-== Status Elsewhere ==
+Status Elsewhere
+----------------
 
 It's often useful to present information about the status of a bug in
 other contexts. Again, the listing-view holds a method which provides us
diff --git a/lib/lp/bugs/doc/externalbugtracker-checkwatches.txt b/lib/lp/bugs/doc/externalbugtracker-checkwatches.txt
index 0f4c01e..42d4c58 100644
--- a/lib/lp/bugs/doc/externalbugtracker-checkwatches.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-checkwatches.txt
@@ -1,4 +1,5 @@
-= External Bug Tracker: checkwatches =
+External Bug Tracker: checkwatches
+==================================
 
 Strictly speaking, checkwatches is the name of a cronscript and a
 module in the Launchpad codebase. In the absence of a more complete
@@ -12,7 +13,8 @@ framework.
   -- Gavin Panella, 2007-07-18
 
 
-== get_external_bugtracker ==
+get_external_bugtracker
+-----------------------
 
 get_external_bugtracker is used to get an ExternalBugTracker suitable
 for a particular bugtracker.
diff --git a/lib/lp/bugs/doc/externalbugtracker-comment-pushing.txt b/lib/lp/bugs/doc/externalbugtracker-comment-pushing.txt
index e64217b..86d0359 100644
--- a/lib/lp/bugs/doc/externalbugtracker-comment-pushing.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-comment-pushing.txt
@@ -1,4 +1,5 @@
-= Pushing comments to external bugtrackers =
+Pushing comments to external bugtrackers
+========================================
 
 Some ExternalBugTrackers support the pushing of comments from Launchpad
 to the remote bug tracker.
@@ -268,7 +269,8 @@ invalid remote comment ID, an error will be raised:
     AssertionError: A remote_comment_id must be specified.
 
 
-== Formatting pushed comments ==
+Formatting pushed comments
+--------------------------
 
 The comments that have been pushed to the remote bugtracker have been
 formatted to include data about the comment in Launchpad.
diff --git a/lib/lp/bugs/doc/externalbugtracker-emailaddress.txt b/lib/lp/bugs/doc/externalbugtracker-emailaddress.txt
index c440f94..9e6adf8 100644
--- a/lib/lp/bugs/doc/externalbugtracker-emailaddress.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-emailaddress.txt
@@ -1,6 +1,8 @@
-= Email addresses as bug trackers =
+Email addresses as bug trackers
+===============================
 
-== The EMAILADDRESS BugTrackerType ==
+The EMAILADDRESS BugTrackerType
+-------------------------------
 
 Launchpad allows users to register an email address as an external bug
 tracker. This means that bugs for that bug tracker can be forwarded to
@@ -66,7 +68,8 @@ the local part of an email address (e.g. <local_name>@foobar.com).
     auto-another.bugtracker
 
 
-== Adding a BugWatch to an upstream email address ==
+Adding a BugWatch to an upstream email address
+----------------------------------------------
 
 We can add a bug watch to an upstream email address in the normal
 fashion. For email addresses, we record the message ID of the mail sent
diff --git a/lib/lp/bugs/doc/externalbugtracker-linking-back.txt b/lib/lp/bugs/doc/externalbugtracker-linking-back.txt
index 32186e3..28b8597 100644
--- a/lib/lp/bugs/doc/externalbugtracker-linking-back.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-linking-back.txt
@@ -1,4 +1,5 @@
-= Remote bugs linking back to Launchpad =
+Remote bugs linking back to Launchpad
+=====================================
 
 Some bug trackers support linking back to bugs in Launchpad. This way we
 can tell external bug trackers that we're watching the bug, and make it
@@ -69,7 +70,8 @@ be related to a bug task, not just a bug.
     ...     external_bugtracker, [bug_watch_without_bugtask])
 
 
-== BugWatchUpdater.linkLaunchpadBug() ==
+BugWatchUpdater.linkLaunchpadBug()
+----------------------------------
 
 The BugWatchUpdater method that does the work of setting the Launchpad
 bug link is linkLaunchpadBug(). This method first retrieves the
diff --git a/lib/lp/bugs/doc/externalbugtracker-mantis-csv.txt b/lib/lp/bugs/doc/externalbugtracker-mantis-csv.txt
index 0cd932f..d9fb120 100644
--- a/lib/lp/bugs/doc/externalbugtracker-mantis-csv.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-mantis-csv.txt
@@ -1,4 +1,5 @@
-= ExternalBugTracker: Mantis =
+ExternalBugTracker: Mantis
+==========================
 
 This covers the implementation of the Mantis bug watch updater when
 used in the "CSV export" mode. The default mode is to page-scrape
@@ -8,7 +9,8 @@ installations work with it (at least two prominent installations
 return empty exports).
 
 
-== Basics ==
+Basics
+------
 
 The class that implements ExternalBugTracker for Mantis is called,
 surprisingly, Mantis! It doesn't do any version probing and simply
@@ -42,7 +44,8 @@ If the status can't be converted an UnknownRemoteStatusError is raised.
     lp.bugs.externalbugtracker.base.UnknownRemoteStatusError: foo: bar
 
 
-== Updating Bug Watches ==
+Updating Bug Watches
+--------------------
 
 Let's set up a BugTracker and some watches for the Example.com Bug
 Tracker:
diff --git a/lib/lp/bugs/doc/externalbugtracker-mantis.txt b/lib/lp/bugs/doc/externalbugtracker-mantis.txt
index bfc1b0a..bf2768b 100644
--- a/lib/lp/bugs/doc/externalbugtracker-mantis.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-mantis.txt
@@ -1,9 +1,11 @@
-= ExternalBugTracker: Mantis =
+ExternalBugTracker: Mantis
+==========================
 
 This covers the implementation of the Mantis bug watch updater.
 
 
-== Basics ==
+Basics
+------
 
 The class that implements ExternalBugTracker for Mantis is called,
 surprisingly, Mantis! It doesn't do any version probing and simply
@@ -45,7 +47,8 @@ If the status can't be converted an UnknownRemoteStatusError is raised.
     lp.bugs.externalbugtracker.base.UnknownRemoteStatusError: foo: bar
 
 
-== Updating Bug Watches ==
+Updating Bug Watches
+--------------------
 
 Let's set up a BugTracker and some watches for the Example.com Bug
 Tracker:
diff --git a/lib/lp/bugs/doc/externalbugtracker-roundup-python-bugs.txt b/lib/lp/bugs/doc/externalbugtracker-roundup-python-bugs.txt
index ee95543..4c2916a 100644
--- a/lib/lp/bugs/doc/externalbugtracker-roundup-python-bugs.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-roundup-python-bugs.txt
@@ -1,4 +1,5 @@
-= ExternalBugTracker: Python =
+ExternalBugTracker: Python
+==========================
 
 This covers the implementation of the ExternalBugTracker class for
 Python bugwatches.
@@ -11,7 +12,8 @@ common to Roundup and Python instances, see
 externalbugtracker-roundup.txt
 
 
-== Status Conversion ==
+Status Conversion
+-----------------
 
 The basic Python bug statuses map to Launchpad bug statuses.
 Roundup.convertRemoteStatus() handles the conversion.
diff --git a/lib/lp/bugs/doc/externalbugtracker-roundup.txt b/lib/lp/bugs/doc/externalbugtracker-roundup.txt
index b4f4963..1d369a2 100644
--- a/lib/lp/bugs/doc/externalbugtracker-roundup.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-roundup.txt
@@ -1,10 +1,12 @@
-= ExternalBugTracker: Roundup =
+ExternalBugTracker: Roundup
+===========================
 
 This covers the implementation of the ExternalBugTracker class for Roundup
 bugwatches.
 
 
-== Basics ==
+Basics
+------
 
 The ExternalBugTracker descendant class which implements methods for updating
 bug watches on Roundup bug trackers is externalbugtracker.Roundup, which
@@ -22,7 +24,8 @@ implements IExternalBugTracker.
     True
 
 
-== Status Conversion ==
+Status Conversion
+-----------------
 
 The basic Roundup bug statuses (i.e. those available by default in new
 Roundup instances) map to Launchpad bug statuses.
@@ -70,7 +73,8 @@ understand an UnknownRemoteStatusError will be raised.
     lp.bugs.externalbugtracker.base.UnknownRemoteStatusError: Unrecognized value for field 1 (status): eggs
 
 
-== Initialization ==
+Initialization
+--------------
 
 Calling initializeRemoteBugDB() on our Roundup instance and passing it a set
 of remote bug IDs will fetch those bug IDs from the server and file them in a
@@ -88,7 +92,8 @@ avoids relying on a working network connection.
     [1]
 
 
-== Export Methods ==
+Export Methods
+--------------
 
 There are two means by which we can export Roundup bug statuses: on a
 bug-by-bug basis and as a batch. When the number of bugs that need updating is
@@ -115,7 +120,8 @@ fetched as a batch:
     GET http://test.roundup/issue?...@startwith=0
 
 
-== Updating Bug Watches ==
+Updating Bug Watches
+--------------------
 
 First, we create some bug watches to test with:
 
diff --git a/lib/lp/bugs/doc/externalbugtracker-rt.txt b/lib/lp/bugs/doc/externalbugtracker-rt.txt
index 215cf9d..2feb460 100644
--- a/lib/lp/bugs/doc/externalbugtracker-rt.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-rt.txt
@@ -1,10 +1,12 @@
-= ExternalBugTracker: RT =
+ExternalBugTracker: RT
+======================
 
 This covers the implementation of an ExternalBugTracker class for RT
 instances.
 
 
-== Basics ==
+Basics
+------
 
 When importing bugs from remote RT instances, we use an RT-specific
 implementation of ExternalBugTracker, RequestTracker.
@@ -22,7 +24,8 @@ implementation of ExternalBugTracker, RequestTracker.
     True
 
 
-== Authentication Credentials ==
+Authentication Credentials
+--------------------------
 
 RT instances require that we log in to be able to export statuses for
 their tickets. The RequestTracker ExternalBugTracker class has a
@@ -45,7 +48,8 @@ configuration files. rt.example.com is known to Launchpad.
     >>> print(pretty(rt_two.credentials))
     {'pass': 'pangalacticgargleblaster', 'user': 'zaphod'}
 
-== Status Conversion ==
+Status Conversion
+-----------------
 
 The RequestTracker class can convert the default RT ticket statuses into
 Launchpad statuses:
@@ -72,7 +76,8 @@ result in an UnknownRemoteStatusError being raised.
     lp.bugs.externalbugtracker.base.UnknownRemoteStatusError: spam
 
 
-== Importance Conversion ==
+Importance Conversion
+---------------------
 
 There is no obvious mapping from ticket priorities to importances. They
 are all imported as Unknown. No exception is raised, because they are
@@ -82,7 +87,8 @@ all unknown.
    'Unknown'
 
 
-== Initialization ==
+Initialization
+--------------
 
 Calling initializeRemoteBugDB() on our RequestTracker instance and
 passing it a set of remote bug IDs will fetch those bug IDs from the
@@ -119,7 +125,8 @@ Subsequent requests use this.
     GET http://example.com/REST/1.0/search/ticket/?...
 
 
-== Export Methods ==
+Export Methods
+--------------
 
 There are two means by which we can export RT bug statuses: on a
 bug-by-bug basis and as a batch. When the number of bugs that need
@@ -166,7 +173,8 @@ This can also be demonstrated for importing bugs as a batch:
       ...
     lp.bugs.externalbugtracker.base.BugTrackerConnectError: ...
 
-== Updating Bug Watches ==
+Updating Bug Watches
+--------------------
 
 First, we create some bug watches to test with. Example.com hosts an RT
 instance which has several bugs that we wish to watch:
@@ -252,7 +260,8 @@ statuses:
     Remote bug 1589: Invalid
 
 
-== Getting the remote product for a bug ==
+Getting the remote product for a bug
+------------------------------------
 
 It's possible to get the remote product for a remote RT bug using
 getRemoteProduct(). In the case of RT, what we refer to in Launchpad as
diff --git a/lib/lp/bugs/doc/externalbugtracker-sourceforge.txt b/lib/lp/bugs/doc/externalbugtracker-sourceforge.txt
index bcaf316..707bbb4 100644
--- a/lib/lp/bugs/doc/externalbugtracker-sourceforge.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-sourceforge.txt
@@ -1,10 +1,12 @@
-= ExternalBugTracker: SourceForge =
+ExternalBugTracker: SourceForge
+===============================
 
 This covers the implementation of the ExternalBugTracker class for
 SourceForge bugwatches.
 
 
-== Basics ==
+Basics
+------
 
 The ExternalBugTracker descendant class which implements methods for
 updating bug watches on SourceForge bug trackers is
@@ -20,7 +22,8 @@ externalbugtracker.SourceForge, which implements IExternalBugTracker.
     True
 
 
-== Status Conversion ==
+Status Conversion
+-----------------
 
 The SourceForge bug status/resolution combinations map to Launchpad bug
 statuses. SourceForge.convertRemoteStatus() handles the conversion.
@@ -73,7 +76,8 @@ understand an UnknownRemoteStatusError will be raised.
     lp.bugs.externalbugtracker.base.UnknownRemoteStatusError: eggs
 
 
-== Initialization ==
+Initialization
+--------------
 
 Calling initializeRemoteBugDB() on our SourceForge instance and passing
 it a set of remote bug IDs will fetch those bug IDs from the server and
@@ -136,7 +140,8 @@ a PrivateRemoteBug error.
     lp.bugs.externalbugtracker.base.PrivateRemoteBug: Bug 99 on http://example.com is private.
 
 
-== Updating Bug Watches ==
+Updating Bug Watches
+--------------------
 
 First, we create some bug watches to test with. Example.com hosts a
 SourceForge instance which has several bugs that we wish to watch:
@@ -260,7 +265,8 @@ statuses:
     Remote bug 1722259: Won't Fix
 
 
-== Getting the remote product for a bug ==
+Getting the remote product for a bug
+------------------------------------
 
 It's possible to get the remote product for a bug by calling
 SourceForge.getRemoteProduct(). In SourceForge's case, what we refer to
diff --git a/lib/lp/bugs/doc/externalbugtracker-trac.txt b/lib/lp/bugs/doc/externalbugtracker-trac.txt
index 2dc976a..53df563 100644
--- a/lib/lp/bugs/doc/externalbugtracker-trac.txt
+++ b/lib/lp/bugs/doc/externalbugtracker-trac.txt
@@ -1,10 +1,12 @@
-= ExternalBugTracker: Trac =
+ExternalBugTracker: Trac
+========================
 
 This covers the implementation of the ExternalBugTracker class for Trac
 bugwatches.
 
 
-== Basics ==
+Basics
+------
 
 The ExternalBugTracker descendant class which implements methods for updating
 bug watches on Trac bug trackers is externalbugtracker.Trac, which implements
@@ -21,7 +23,8 @@ IExternalBugTracker.
     True
 
 
-== LP plugin ==
+LP plugin
+---------
 
 Some Trac instances have a plugin installed to make it easier for us to
 communicate with them. getExternalBugTrackerToUse() probes the bug
@@ -99,7 +102,8 @@ persists.
     True
 
 
-== Status Conversion ==
+Status Conversion
+-----------------
 
 The basic Trac ticket statuses map to Launchpad bug statuses.
 Trac.convertRemoteStatus() handles the conversion.
@@ -140,7 +144,8 @@ an UnknownRemoteStatusError will be raised.
     lp.bugs.externalbugtracker.base.UnknownRemoteStatusError: eggs
 
 
-== Initialization ==
+Initialization
+--------------
 
 Calling initializeRemoteBugDB() on our Trac instance and passing it a set of
 remote bug IDs will fetch those bug IDs from the server and file them in a
@@ -164,7 +169,8 @@ If we initialize with a different set of keys we overwrite the first set:
     [6, 7, 8, 9, 10, 11, 12]
 
 
-== Export Methods ==
+Export Methods
+--------------
 
 There are two means by which we can export Trac bug statuses: on a bug-by-bug
 basis and as a batch. When the number of bugs that need updating is less than
@@ -263,7 +269,8 @@ export, it will raise an UnparsableBugData error.
     lp.bugs.externalbugtracker.base.UnparsableBugData: External bugtracker http://test.trac does not define all the necessary fields for bug status imports (Defined field names: ['<html>']).
 
 
-== Updating Bug Watches ==
+Updating Bug Watches
+--------------------
 
 First, we create some bug watches to test with:
 
diff --git a/lib/lp/bugs/doc/product-update-remote-product-script.txt b/lib/lp/bugs/doc/product-update-remote-product-script.txt
index 4f76945..c0801b6 100644
--- a/lib/lp/bugs/doc/product-update-remote-product-script.txt
+++ b/lib/lp/bugs/doc/product-update-remote-product-script.txt
@@ -1,4 +1,5 @@
-== update-remote-product.py ==
+update-remote-product.py
+------------------------
 
 The script that uses RemoteProductUpdater is update-remote-product.py.
 
diff --git a/lib/lp/bugs/doc/products-with-no-remote-product.txt b/lib/lp/bugs/doc/products-with-no-remote-product.txt
index 6646de1..bb3d587 100644
--- a/lib/lp/bugs/doc/products-with-no-remote-product.txt
+++ b/lib/lp/bugs/doc/products-with-no-remote-product.txt
@@ -1,4 +1,5 @@
-= Products with no remote_product =
+Products with no remote_product
+===============================
 
 Product.remote_product is used to keep track of which remote product in
 an upstream bug tracker, a Product registered in Launchpad corresponds
diff --git a/lib/lp/bugs/doc/treelookup.txt b/lib/lp/bugs/doc/treelookup.txt
index 7dfd661..7ef5b4e 100644
--- a/lib/lp/bugs/doc/treelookup.txt
+++ b/lib/lp/bugs/doc/treelookup.txt
@@ -1,4 +1,5 @@
-= Doing lookups in a tree =
+Doing lookups in a tree
+=======================
 
   >>> from lp.bugs.adapters.treelookup import (
   ...     LookupBranch, LookupTree)
@@ -35,7 +36,8 @@ tree, because it would not make sense for it to appear in any other
 position.
 
 
-== Creation ==
+Creation
+--------
 
   >>> tree = LookupTree(
   ...     ('Snack', LookupTree(
@@ -92,7 +94,8 @@ instances), `LookupTree._verify` also checks that every branch is a
   TypeError: Not a LookupBranch: ...'Greenland'
 
 
-== Searching ==
+Searching
+---------
 
 Just call `tree.find`.
 
@@ -113,7 +116,8 @@ But an exception is raised if it does not reach a leaf.
   KeyError: ...'Snack'
 
 
-== Development ==
+Development
+-----------
 
 `LookupTree` makes development easy, because `describe` gives a
 complete description of the tree you've created.
@@ -152,7 +156,8 @@ Simple keys are shown without quotes, to aid readability, and default
 branches are shown with '*' as the key.
 
 
-== Pruning ==
+Pruning
+-------
 
 During tree creation, branches which have keys that already appear in
 earlier branches are cloned and have those already seen keys
@@ -180,7 +185,8 @@ branches with keys are candidates for being discarded.
       )
 
 
-== Documentation ==
+Documentation
+-------------
 
 You can discover the minimum and maximum depth of a tree.
 
diff --git a/lib/lp/bugs/stories/bug-also-affects/xx-also-affects-distribution-default-values.txt b/lib/lp/bugs/stories/bug-also-affects/xx-also-affects-distribution-default-values.txt
index f5c7d6e..c6a1a27 100644
--- a/lib/lp/bugs/stories/bug-also-affects/xx-also-affects-distribution-default-values.txt
+++ b/lib/lp/bugs/stories/bug-also-affects/xx-also-affects-distribution-default-values.txt
@@ -1,4 +1,5 @@
-= Default values on the +distrotask form =
+Default values on the +distrotask form
+======================================
 
 Source packages often share names across distributions, especially
 Debian and Ubuntu. So when you want to indicate that the bug affects
diff --git a/lib/lp/bugs/stories/bug-also-affects/xx-also-affects-new-upstream.txt b/lib/lp/bugs/stories/bug-also-affects/xx-also-affects-new-upstream.txt
index cbfe9a9..876f24e 100644
--- a/lib/lp/bugs/stories/bug-also-affects/xx-also-affects-new-upstream.txt
+++ b/lib/lp/bugs/stories/bug-also-affects/xx-also-affects-new-upstream.txt
@@ -1,4 +1,5 @@
-= Registering an upstream affected by a given bug =
+Registering an upstream affected by a given bug
+===============================================
 
 The test browser does not support javascript
     >>> user_browser.open(
@@ -93,7 +94,8 @@ the bug as affecting another (unregistered) upstream.
     The Bar Project ...   auto-bugs.foo.org #123
     The Bar Project ...   auto-bugs.foo.org #421
 
-== Error handling ==
+Error handling
+--------------
 
 If the URL of the remote bug is not recognized by Launchpad, we'll tell the
 user and ask them to check if it's correct.
diff --git a/lib/lp/bugs/stories/bug-also-affects/xx-bugtracker-information.txt b/lib/lp/bugs/stories/bug-also-affects/xx-bugtracker-information.txt
index 3ea9322..a238e64 100644
--- a/lib/lp/bugs/stories/bug-also-affects/xx-bugtracker-information.txt
+++ b/lib/lp/bugs/stories/bug-also-affects/xx-bugtracker-information.txt
@@ -1,4 +1,5 @@
-= Bug tracker information =
+Bug tracker information
+=======================
 
 If a product doesn't use Launchpad to track its bugs, there's
 information about the product's bug tracker when adding an upstream
diff --git a/lib/lp/bugs/stories/bug-also-affects/xx-duplicate-bugwatches.txt b/lib/lp/bugs/stories/bug-also-affects/xx-duplicate-bugwatches.txt
index 9d380cf..53c99f1 100644
--- a/lib/lp/bugs/stories/bug-also-affects/xx-duplicate-bugwatches.txt
+++ b/lib/lp/bugs/stories/bug-also-affects/xx-duplicate-bugwatches.txt
@@ -1,6 +1,8 @@
-= Duplicate bug watches =
+Duplicate bug watches
+=====================
 
-== Adding the same bug watch twice to a bug ==
+Adding the same bug watch twice to a bug
+----------------------------------------
 
 When adding bug watches, existing bug watches are re-used if there
 already is one pointing to the same remote bug. For example, let's start
@@ -64,7 +66,8 @@ same bug watch.
     pmount (Debian)     ... Unknown  Unknown  debbugs #42
 
 
-== Adding the same bug watch to two different bugs ==
+Adding the same bug watch to two different bugs
+-----------------------------------------------
 
 If a bug watch which is already added to another bug is added, a
 notification is added linking to the bug. This is useful for detecting
diff --git a/lib/lp/bugs/stories/bug-also-affects/xx-request-distribution-no-release-fix.txt b/lib/lp/bugs/stories/bug-also-affects/xx-request-distribution-no-release-fix.txt
index a840405..072ba0a 100644
--- a/lib/lp/bugs/stories/bug-also-affects/xx-request-distribution-no-release-fix.txt
+++ b/lib/lp/bugs/stories/bug-also-affects/xx-request-distribution-no-release-fix.txt
@@ -1,10 +1,12 @@
-= Requesting a fix for a distribution with no current release =
+Requesting a fix for a distribution with no current release
+===========================================================
 
 Sometimes a distribution might not have any releases, thus it won't have
 a current release either. In this case it will still be possible to
 request a fix for these releases.
 
-== A distribution using Launchpad ==
+A distribution using Launchpad
+------------------------------
 
 Gentoo is currently using Launchpad.
 
@@ -22,7 +24,8 @@ Any user can request a fix for it.
     >>> user_browser.url
     'http://bugs.launchpad.test/gentoo/+bug/4'
 
-== A distribution not using Launchpad ==
+A distribution not using Launchpad
+----------------------------------
 
 If we change Gentoo not to use Launchpad, any user can still add a task and
 link to a external bug for it.
diff --git a/lib/lp/bugs/stories/bug-also-affects/xx-upstream-bugtracker-links.txt b/lib/lp/bugs/stories/bug-also-affects/xx-upstream-bugtracker-links.txt
index 9cc69fc..1d29a68 100644
--- a/lib/lp/bugs/stories/bug-also-affects/xx-upstream-bugtracker-links.txt
+++ b/lib/lp/bugs/stories/bug-also-affects/xx-upstream-bugtracker-links.txt
@@ -1,4 +1,5 @@
-= Links to upstream bug trackers =
+Links to upstream bug trackers
+==============================
 
 Sometimes people will want to mark a bug as being upstream but will
 either not know what the bug's upstream URL is or will know that the bug
diff --git a/lib/lp/bugs/stories/bug-release-management/nomination-navigation.txt b/lib/lp/bugs/stories/bug-release-management/nomination-navigation.txt
index 5c951e4..b974d94 100644
--- a/lib/lp/bugs/stories/bug-release-management/nomination-navigation.txt
+++ b/lib/lp/bugs/stories/bug-release-management/nomination-navigation.txt
@@ -1,4 +1,5 @@
-= Bug nomination navigation =
+Bug nomination navigation
+=========================
 
 Most people don't see the separate page for approving or declining a
 release nomination for a bug, because it's handled using an expandable
diff --git a/lib/lp/bugs/stories/bug-tags/xx-searching-for-tags.txt b/lib/lp/bugs/stories/bug-tags/xx-searching-for-tags.txt
index c51e388..4c45b07 100644
--- a/lib/lp/bugs/stories/bug-tags/xx-searching-for-tags.txt
+++ b/lib/lp/bugs/stories/bug-tags/xx-searching-for-tags.txt
@@ -1,4 +1,5 @@
-= Searching for bug tags =
+Searching for bug tags
+======================
 
 On the advanced search page it's possible to search for a specific tag.
 
@@ -38,7 +39,8 @@ If an invalid tag name is entered, an error message will be displayed.
     allowed after the first character.
 
 
-== Cross-Site Scripting, or XSS ==
+Cross-Site Scripting, or XSS
+----------------------------
 
 The tags field and its related messages are properly escaped in order
 to prevent XSS.
diff --git a/lib/lp/bugs/stories/bugattachments/xx-delete-bug-attachment.txt b/lib/lp/bugs/stories/bugattachments/xx-delete-bug-attachment.txt
index b9f7292..00561d1 100644
--- a/lib/lp/bugs/stories/bugattachments/xx-delete-bug-attachment.txt
+++ b/lib/lp/bugs/stories/bugattachments/xx-delete-bug-attachment.txt
@@ -1,4 +1,5 @@
-= Deleting bug attachments =
+Deleting bug attachments
+========================
 
 If some attachment gets added which isn't relevant to the bug, it can be
 deleted again from the bug attachment edit page.
diff --git a/lib/lp/bugs/stories/bugattachments/xx-display-filesize-attachment.txt b/lib/lp/bugs/stories/bugattachments/xx-display-filesize-attachment.txt
index 83571e0..4d94cd4 100644
--- a/lib/lp/bugs/stories/bugattachments/xx-display-filesize-attachment.txt
+++ b/lib/lp/bugs/stories/bugattachments/xx-display-filesize-attachment.txt
@@ -1,4 +1,5 @@
-== Display of filesize and mime type of attachments ==
+Display of filesize and mime type of attachments
+------------------------------------------------
 
 File size and mime type are displayed for each attachment
 
diff --git a/lib/lp/bugs/stories/bugs/xx-add-comment-bugtask-edit.txt b/lib/lp/bugs/stories/bugs/xx-add-comment-bugtask-edit.txt
index d2e6dcb..1698d19 100644
--- a/lib/lp/bugs/stories/bugs/xx-add-comment-bugtask-edit.txt
+++ b/lib/lp/bugs/stories/bugs/xx-add-comment-bugtask-edit.txt
@@ -1,4 +1,5 @@
-= Add a comment while editing the bugtask =
+Add a comment while editing the bugtask
+=======================================
 
 When editing a bug task it's possible to add a comment as well. It's not
 necessary to actually edit the bug task in order to add the comment,
diff --git a/lib/lp/bugs/stories/bugs/xx-add-comment-distribution-no-current-release.txt b/lib/lp/bugs/stories/bugs/xx-add-comment-distribution-no-current-release.txt
index b90a49f..f68811c 100644
--- a/lib/lp/bugs/stories/bugs/xx-add-comment-distribution-no-current-release.txt
+++ b/lib/lp/bugs/stories/bugs/xx-add-comment-distribution-no-current-release.txt
@@ -1,4 +1,5 @@
-= Add a comment on a bug on a distribution with no current release =
+Add a comment on a bug on a distribution with no current release
+================================================================
 
 If a bug is reported distribution with no current release, like Gentoo,
 it's still possible to add comments to the bug.
diff --git a/lib/lp/bugs/stories/bugs/xx-add-comment-with-bugwatch-and-cve.txt b/lib/lp/bugs/stories/bugs/xx-add-comment-with-bugwatch-and-cve.txt
index 6228d8c..147cc45 100644
--- a/lib/lp/bugs/stories/bugs/xx-add-comment-with-bugwatch-and-cve.txt
+++ b/lib/lp/bugs/stories/bugs/xx-add-comment-with-bugwatch-and-cve.txt
@@ -1,4 +1,5 @@
-= links to remote bug reports and CVEs in bug comments =
+links to remote bug reports and CVEs in bug comments
+====================================================
 
 When a comment is added to a bug, links to "remote" bug reports and CVEs are
 added to the bugwatches resp CVEs related to this bug
diff --git a/lib/lp/bugs/stories/bugs/xx-bug-affects-me-too.txt b/lib/lp/bugs/stories/bugs/xx-bug-affects-me-too.txt
index e1c6458..33ce24b 100644
--- a/lib/lp/bugs/stories/bugs/xx-bug-affects-me-too.txt
+++ b/lib/lp/bugs/stories/bugs/xx-bug-affects-me-too.txt
@@ -1,4 +1,5 @@
-= Marking a bug as affecting the user =
+Marking a bug as affecting the user
+===================================
 
 Users can mark bugs as affecting them. Let's create a sample bug to
 try this out.
@@ -66,7 +67,8 @@ Back at the bug page, the text changes once again.
    This bug affects 1 person, but not you
 
 
-== Anonymous users ==
+Anonymous users
+---------------
 
 Anonymous users just see the number of affected users.
 
@@ -87,7 +89,8 @@ appear at all to anonymous users.
    None
 
 
-== Static and dynamic support ==
+Static and dynamic support
+--------------------------
 
 A bug page contains markup to support both static (no Javascript) and
 dynamic (Javascript enabled) scenarios.
diff --git a/lib/lp/bugs/stories/bugs/xx-bug-heat-on-bug-page.txt b/lib/lp/bugs/stories/bugs/xx-bug-heat-on-bug-page.txt
index d42f14c..141f6e8 100644
--- a/lib/lp/bugs/stories/bugs/xx-bug-heat-on-bug-page.txt
+++ b/lib/lp/bugs/stories/bugs/xx-bug-heat-on-bug-page.txt
@@ -1,4 +1,5 @@
-= Bug heat on bug page =
+Bug heat on bug page
+====================
 
 Bug heat appears on the bug index page:
 
diff --git a/lib/lp/bugs/stories/bugs/xx-bug-hidden-comments.txt b/lib/lp/bugs/stories/bugs/xx-bug-hidden-comments.txt
index e92f1ef..31fb476 100644
--- a/lib/lp/bugs/stories/bugs/xx-bug-hidden-comments.txt
+++ b/lib/lp/bugs/stories/bugs/xx-bug-hidden-comments.txt
@@ -1,4 +1,5 @@
-= Hide bug comments =
+Hide bug comments
+=================
 
 Comments that have had their visible attribute set to False
 will not show up when browsing the comment list for a bug.
diff --git a/lib/lp/bugs/stories/bugs/xx-bug-nomination-table-row.txt b/lib/lp/bugs/stories/bugs/xx-bug-nomination-table-row.txt
index b1697d3..f5b0609 100644
--- a/lib/lp/bugs/stories/bugs/xx-bug-nomination-table-row.txt
+++ b/lib/lp/bugs/stories/bugs/xx-bug-nomination-table-row.txt
@@ -1,4 +1,5 @@
-= Bug nominations =
+Bug nominations
+===============
 
 Bug nominations are displayed in the table at the top of the bug page,
 using the +bugtasks-and-nominations-table-row view. This view allows
diff --git a/lib/lp/bugs/stories/bugs/xx-bug-text-pages.txt b/lib/lp/bugs/stories/bugs/xx-bug-text-pages.txt
index aedbffd..d2e9c6d 100644
--- a/lib/lp/bugs/stories/bugs/xx-bug-text-pages.txt
+++ b/lib/lp/bugs/stories/bugs/xx-bug-text-pages.txt
@@ -1,4 +1,5 @@
-= Bug Text Pages =
+Bug Text Pages
+==============
 
 Launchpad provides a way for users to view textual descriptions of bug reports,
 as an alternative to the graphical user interface.
@@ -43,7 +44,8 @@ toggle away from Fix Released we must be the target owner):
     >>> flush_database_updates()
 
 
-== Text Pages from a Bug Context ==
+Text Pages from a Bug Context
+-----------------------------
 
 Users can view a textual description of any bug at that bug's text page,
 according to the following URL pattern:
@@ -167,7 +169,8 @@ The comments are represented as a MIME message.
     comment for file with space
 
 
-== Text Pages from a Bug Task Context ==
+Text Pages from a Bug Task Context
+----------------------------------
 
 Users can also view a textual description of a bug from the context of a task
 relating to that bug, according to the following URL pattern:
@@ -234,7 +237,8 @@ The only differences are the download URLs of bug attachments:
     http://bugs.launchpad.test/bugs/1/.../+files/bug-patch.diff text/plain
     http://bugs.launchpad.test/firefox/+bug/.../+files/bug-patch.diff text/plain
 
-== Duplicate Bugs ==
+Duplicate Bugs
+--------------
 
 When one bug duplicates another bug, the textual description includes the
 duplicated bug's ID:
@@ -268,7 +272,8 @@ duplicate bug IDs:
     ...
 
 
-== Bug Lists ==
+Bug Lists
+---------
 
 Users can also see a list of all bug IDs for a given target by viewing that
 product's bugs text page, according to the following URL pattern:
@@ -322,7 +327,8 @@ This page is also available for project groups.
     4
 
 
-== Private bugs ==
+Private bugs
+------------
 
 When a bug is private, the textual description reflects this:
 
diff --git a/lib/lp/bugs/stories/bugs/xx-distributionsourcepackage-bugs.txt b/lib/lp/bugs/stories/bugs/xx-distributionsourcepackage-bugs.txt
index da5542b..4608aa3 100644
--- a/lib/lp/bugs/stories/bugs/xx-distributionsourcepackage-bugs.txt
+++ b/lib/lp/bugs/stories/bugs/xx-distributionsourcepackage-bugs.txt
@@ -1,4 +1,5 @@
-= Distribution Source Package Bugs =
+Distribution Source Package Bugs
+================================
 
 This page is like most bug listing pages, but it also has a portlet
 "portlet-publishing-details" giving information about the latest published
diff --git a/lib/lp/bugs/stories/bugs/xx-distrorelease-bugs-page.txt b/lib/lp/bugs/stories/bugs/xx-distrorelease-bugs-page.txt
index 7d95a21..5be0bc6 100644
--- a/lib/lp/bugs/stories/bugs/xx-distrorelease-bugs-page.txt
+++ b/lib/lp/bugs/stories/bugs/xx-distrorelease-bugs-page.txt
@@ -1,4 +1,5 @@
-== The Distribution Series Bugs Page ==
+The Distribution Series Bugs Page
+---------------------------------
 
 The +bugs page for a distribution series presents some basic information the
 bugs, as well as a listing.
@@ -26,7 +27,8 @@ It also has a link to subscribe to bug mail.
     http://bugs.launchpad.test/ubuntu/warty/+subscribe
 
 
-== Bugs Fixed Elsewhere ==
+Bugs Fixed Elsewhere
+--------------------
 
 The Bugs frontpage includes the number of bugs that are fixed in some
 other context.
@@ -46,7 +48,8 @@ The link takes you to the list of the bugs fixed elsewhere.
     ...
 
 
-== Expirable Bugs ==
+Expirable Bugs
+--------------
 
 The bugs page displays the number of Incomplete, unattended bugs that
 can expire when the project has enabled bug expiration.
diff --git a/lib/lp/bugs/stories/bugs/xx-duplicate-of-private-bug.txt b/lib/lp/bugs/stories/bugs/xx-duplicate-of-private-bug.txt
index 68bf232..c25ee8c 100644
--- a/lib/lp/bugs/stories/bugs/xx-duplicate-of-private-bug.txt
+++ b/lib/lp/bugs/stories/bugs/xx-duplicate-of-private-bug.txt
@@ -1,4 +1,5 @@
-= Showing a duplicate of a private bug =
+Showing a duplicate of a private bug
+====================================
 
 When showing a duplicate of a private bug, the title of the private
 bug is not included in the page if the user does not have permission
diff --git a/lib/lp/bugs/stories/bugs/xx-edit-no-currentrelease-distribution-task.txt b/lib/lp/bugs/stories/bugs/xx-edit-no-currentrelease-distribution-task.txt
index 6a0539e..1d0245d 100644
--- a/lib/lp/bugs/stories/bugs/xx-edit-no-currentrelease-distribution-task.txt
+++ b/lib/lp/bugs/stories/bugs/xx-edit-no-currentrelease-distribution-task.txt
@@ -1,4 +1,5 @@
-= Editing a Distribution task with no current release =
+Editing a Distribution task with no current release
+===================================================
 
 If a distribution doesn't have a current release, like Gentoo, it's
 still possible to edit its tasks from the bug page. There are no Gentoo
diff --git a/lib/lp/bugs/stories/bugs/xx-front-page-search.txt b/lib/lp/bugs/stories/bugs/xx-front-page-search.txt
index c7914a7..7367a15 100644
--- a/lib/lp/bugs/stories/bugs/xx-front-page-search.txt
+++ b/lib/lp/bugs/stories/bugs/xx-front-page-search.txt
@@ -1,4 +1,5 @@
-= Searching from the Bugs front page =
+Searching from the Bugs front page
+==================================
 
 It's possible to search bug reports across all of Launchpad from the
 Bugs front page.
@@ -14,7 +15,8 @@ Either all projects, or a specific one can be searched.
     >>> anon_browser.getControl('One project') is not None
     True
 
-== Searching all projects ==
+Searching all projects
+----------------------
 
 When choosing to search all the projects, all open bug reports in
 Launchpad will be searched, and the bug target will be visible in the
@@ -69,7 +71,8 @@ the form at the front page.
     >>> anon_browser.title
     'Search all bug reports'
 
-== Searching one project ==
+Searching one project
+---------------------
 
 If the user chooses to search only one project, they will be forwarded to
 the project's bug listing, and the search will be performed there. If no
@@ -116,7 +119,8 @@ support javascript, so a 'Find' link pointing to /bugs is displayed.
 'Project' in this context means either a product, distribution or a
 project group.
 
-=== Searching a product ===
+Searching a product
+...................
 
     >>> anon_browser.open('http://bugs.launchpad.test/')
     >>> anon_browser.getControl('One project').selected = True
@@ -131,7 +135,8 @@ project group.
     7 A test bug Evolution
       Medium New
 
-=== Searching a project ===
+Searching a project
+...................
 
     >>> anon_browser.open('http://bugs.launchpad.test/')
     >>> anon_browser.getControl('One project').selected = True
@@ -146,7 +151,8 @@ project group.
     7 A test bug
       Evolution Medium New
 
-=== Searching a distribution ===
+Searching a distribution
+........................
 
     >>> anon_browser.open('http://bugs.launchpad.test/')
     >>> anon_browser.getControl('One project').selected = True
@@ -161,7 +167,8 @@ project group.
     10 another test bug
        linux-source-2.6.15 (Ubuntu)  Medium  New
 
-=== Jumping to a bug ===
+Jumping to a bug
+................
 
 Like with all other bug searches, it's possible to jump a bug by
 specifying only the bug id as the search term.
diff --git a/lib/lp/bugs/stories/bugs/xx-front-page-statistics.txt b/lib/lp/bugs/stories/bugs/xx-front-page-statistics.txt
index 918a76e..48782c7 100644
--- a/lib/lp/bugs/stories/bugs/xx-front-page-statistics.txt
+++ b/lib/lp/bugs/stories/bugs/xx-front-page-statistics.txt
@@ -1,4 +1,5 @@
-= Launchpad Bug Statistics =
+Launchpad Bug Statistics
+========================
 
 The Bugs front page shows some statistics:
 
diff --git a/lib/lp/bugs/stories/bugs/xx-incomplete-bugs.txt b/lib/lp/bugs/stories/bugs/xx-incomplete-bugs.txt
index f93df7f..b54b9f1 100644
--- a/lib/lp/bugs/stories/bugs/xx-incomplete-bugs.txt
+++ b/lib/lp/bugs/stories/bugs/xx-incomplete-bugs.txt
@@ -1,4 +1,5 @@
-= Incomplete bugs =
+Incomplete bugs
+===============
 
 Bugs can have their status set to 'Incomplete', to indicate that more
 information is required before they can be confirmed.
@@ -79,7 +80,8 @@ incomplete bugs without response.
     False
 
 
-== Bugs that can expire display a notice ==
+Bugs that can expire display a notice
+-------------------------------------
 
 Projects that use Launchpad to track bugs will expire 'Incomplete'
 bugs after the configured expiration age has passed. The rules
@@ -129,7 +131,8 @@ date. We alter the date_last_updated field of bug 11 to demonstrate this.
     >>> user_browser.getLink('find out why').url
     'https://help.launchpad.net/BugExpiry'
 
-== The expirable bug search ==
+The expirable bug search
+------------------------
 
 Users can view a list of expirable bugs via a link on the project's
 bug page. To see the behaviour of the bug listing, we need another
@@ -213,7 +216,8 @@ Jokosher's bug page.
     12  Copy, Cut and Delete operations should work ...
 
 
-== Incomplete bugs that do not expire ==
+Incomplete bugs that do not expire
+----------------------------------
 
 Debian does not use launchpad to track bugs, so its incomplete bugs
 cannot expire. No Privileges Person sets a Debian bug to Incomplete,
@@ -246,7 +250,8 @@ expirable bugs they read that Debian does not use bug expiration.
     updating the project's details. See Bugs/Expiry.
 
 
-== Default search parameters for incomplete bugs ==
+Default search parameters for incomplete bugs
+---------------------------------------------
 
 Default bug searches look for both Incomplete (with response) and
 Incomplete (without response) bugs.
diff --git a/lib/lp/bugs/stories/bugs/xx-project-bugs-page.txt b/lib/lp/bugs/stories/bugs/xx-project-bugs-page.txt
index 1ac1b71..6d9ad58 100644
--- a/lib/lp/bugs/stories/bugs/xx-project-bugs-page.txt
+++ b/lib/lp/bugs/stories/bugs/xx-project-bugs-page.txt
@@ -1,4 +1,5 @@
-= The ProjectGroup Bugs Page =
+The ProjectGroup Bugs Page
+==========================
 
 The default page for a ProjectGroup on the bugs domain shows the bug listing
 for the ProjectGroup.
diff --git a/lib/lp/bugs/stories/bugs/xx-unique-ids-on-bug-page.txt b/lib/lp/bugs/stories/bugs/xx-unique-ids-on-bug-page.txt
index 5fc9584..b183d8f 100644
--- a/lib/lp/bugs/stories/bugs/xx-unique-ids-on-bug-page.txt
+++ b/lib/lp/bugs/stories/bugs/xx-unique-ids-on-bug-page.txt
@@ -1,4 +1,5 @@
-= Inline Editing of BugTasks =
+Inline Editing of BugTasks
+==========================
 
 On the bug page, the bugtasks are editable inline. This means that
 basically the same form is included on the page for each bugtask. Even
diff --git a/lib/lp/bugs/stories/bugtask-management/xx-bug-privileged-statuses.txt b/lib/lp/bugs/stories/bugtask-management/xx-bug-privileged-statuses.txt
index fe928ec..ff2d0cd 100644
--- a/lib/lp/bugs/stories/bugtask-management/xx-bug-privileged-statuses.txt
+++ b/lib/lp/bugs/stories/bugtask-management/xx-bug-privileged-statuses.txt
@@ -1,4 +1,5 @@
-= Bug Privileged Statuses =
+Bug Privileged Statuses
+=======================
 
 Some statuses, e.g. Won't Fix, are restricted. Only members of the Bug
 Supervisor team may change a bug to that status.
@@ -7,7 +8,8 @@ Supervisor team may change a bug to that status.
     >>> def print_highlighted_bugtask(browser):
     ...     print_bug_affects_table(browser.contents, highlighted_only=True)
 
-== Unprivileged users ==
+Unprivileged users
+------------------
 
     >>> user_browser.open(
     ...     'http://bugs.launchpad.test/ubuntu/+source/'
@@ -50,7 +52,8 @@ those statuses are not shown in the UI:
     ...
     zope.testbrowser.browser.ItemNotFoundError: Triaged
 
-== Bug Supervisor ==
+Bug Supervisor
+--------------
 
 Ubuntu needs a Bug Supervisor first of all:
 
diff --git a/lib/lp/bugs/stories/bugtask-management/xx-edit-email-address-bugtask.txt b/lib/lp/bugs/stories/bugtask-management/xx-edit-email-address-bugtask.txt
index f42e154..a238b7c 100644
--- a/lib/lp/bugs/stories/bugtask-management/xx-edit-email-address-bugtask.txt
+++ b/lib/lp/bugs/stories/bugtask-management/xx-edit-email-address-bugtask.txt
@@ -1,4 +1,5 @@
-= Editing Email Address bugtasks =
+Editing Email Address bugtasks
+==============================
 
     >>> import transaction
     >>> from zope.component import getUtility
@@ -34,7 +35,8 @@
     ...     print('Status: %s\nImportance: %s' % (status, importance))
 
 
-== "Normal" (not Email Address) bugtasks ==
+"Normal" (not Email Address) bugtasks
+-------------------------------------
 
 Normally, it's not possible to edit the status or importance of a
 bugtask associated with a bugwatch that is linked to an external bug
@@ -95,7 +97,8 @@ And the bug supervisor can't see the widgets either.
     Importance: False
 
 
-== Email Address bugtasks ==
+Email Address bugtasks
+----------------------
 
 The status and importance of a bugtask with an email address bugwatch
 will be editable.
diff --git a/lib/lp/bugs/stories/bugtask-searches/xx-filter-by-linked-branches.txt b/lib/lp/bugs/stories/bugtask-searches/xx-filter-by-linked-branches.txt
index 2d0e8fe..a7514ff 100644
--- a/lib/lp/bugs/stories/bugtask-searches/xx-filter-by-linked-branches.txt
+++ b/lib/lp/bugs/stories/bugtask-searches/xx-filter-by-linked-branches.txt
@@ -1,4 +1,5 @@
-= Searching for bugs with linked branches =
+Searching for bugs with linked branches
+=======================================
 
 Using the "advanced search" form, we can limit a bug task search
 to bugs that are linked to branches or to bugs that are not linked
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 2076c5b..e6921f7 100644
--- a/lib/lp/bugs/stories/bugtask-searches/xx-listing-basics.txt
+++ b/lib/lp/bugs/stories/bugtask-searches/xx-listing-basics.txt
@@ -1,4 +1,5 @@
-= Bug listings =
+Bug listings
+============
 
 This test looks at various aspects of bug listings. Here's a very basic
 use case: Sample Person views the bug task listing for the Mozilla
@@ -35,7 +36,8 @@ But you can make it show fixed ones to:
     8 Printing doesn't work mozilla-firefox (Debian) Medium Fix Released
 
 
-== Example listings ==
+Example listings
+----------------
 
 An anonymous user views the bug tasks in upstream Ubuntu.
 
@@ -96,7 +98,8 @@ Do an advanced search with dupes turned on and find the duplicate in the results
      Mozilla Firefox Low New
 
 
-== Critical bugs ==
+Critical bugs
+-------------
 
 A list of critical bugs reported in a given upstream can be viewed by
 clicking the "critical" quick search link. Debian has no open critical bugs:
@@ -113,7 +116,8 @@ But Firefox has a fixed one that Foo Bar can see:
      Mozilla Firefox Critical New
 
 
-== My todo list ==
+My todo list
+------------
 
 The "my todo list" link gives the logged in user the ability to
 quickly see which bugs have been assigned to them.
@@ -130,7 +134,8 @@ This also works for upstream listings:
      Mozilla Firefox Critical New
 
 
-== Looking at unassigned bugs ==
+Looking at unassigned bugs
+--------------------------
 
 View the unassigned bug tasks listing as user Sample Person.
 
@@ -140,7 +145,8 @@ View the unassigned bug tasks listing as user Sample Person.
      Mozilla Firefox Medium New
 
 
-== Search criteria is persistent ==
+Search criteria is persistent
+-----------------------------
 
 The bug listing pages save their search criteria.
 
@@ -167,7 +173,8 @@ The result set is filtered to show only New bugs.
     2 Blackhole Trash folder Ubuntu Medium New
 
 
-== Searching for simple strings ==
+Searching for simple strings
+----------------------------
 
 The bugtask search facility supports searching on a simple text
 string.
@@ -199,7 +206,8 @@ it'll say so.
     ...
 
 
-== Bug Badge Decoration ==
+Bug Badge Decoration
+--------------------
 
 We display bug badges for associated branches, specifications, patches, etc.
 
@@ -265,7 +273,8 @@ Patches also appear as badges in bug listings.
       Badge: haspatch
 
 
-== Bug heat in listings ==
+Bug heat in listings
+--------------------
 
 Bug listings display the bug heat in the last column. Heat is displayed
 as a number.
diff --git a/lib/lp/bugs/stories/bugtask-searches/xx-old-urls-still-work.txt b/lib/lp/bugs/stories/bugtask-searches/xx-old-urls-still-work.txt
index 99d8893..2992c0b 100644
--- a/lib/lp/bugs/stories/bugtask-searches/xx-old-urls-still-work.txt
+++ b/lib/lp/bugs/stories/bugtask-searches/xx-old-urls-still-work.txt
@@ -1,4 +1,5 @@
-= Keeping old bookmarks working =
+Keeping old bookmarks working
+=============================
 
 As part of the bug workflow spec various statuses are being changed
 but we need old bookmarks to keep working with the status names.
@@ -70,7 +71,8 @@ the new status names in place of the old.
     field.status:list=Unconfirmed --> field.status:list=New
     field.status:list=Needs Info  --> field.status:list=Incomplete
 
-== Assigned, Reported and Subscribed Bugs ==
+Assigned, Reported and Subscribed Bugs
+--------------------------------------
 
 Bugs searched for in the context of a person or team are redirected
 too.
diff --git a/lib/lp/bugs/stories/bugtracker/xx-bugtracker-handshake-tokens.txt b/lib/lp/bugs/stories/bugtracker/xx-bugtracker-handshake-tokens.txt
index ba0cc92..d8f2e1a 100644
--- a/lib/lp/bugs/stories/bugtracker/xx-bugtracker-handshake-tokens.txt
+++ b/lib/lp/bugs/stories/bugtracker/xx-bugtracker-handshake-tokens.txt
@@ -1,4 +1,5 @@
-= Handling BugTracker handshake tokens =
+Handling BugTracker handshake tokens
+====================================
 
 Launchpad can generate LoginTokens which can then be used to
 authenticate it with remote bug trackers. Generating these tokens is
diff --git a/lib/lp/bugs/stories/bugwatches/xx-bugwatch-comments.txt b/lib/lp/bugs/stories/bugwatches/xx-bugwatch-comments.txt
index 576043d..b64a470 100644
--- a/lib/lp/bugs/stories/bugwatches/xx-bugwatch-comments.txt
+++ b/lib/lp/bugs/stories/bugwatches/xx-bugwatch-comments.txt
@@ -1,4 +1,5 @@
-= Comments Imported From a Bug Watch =
+Comments Imported From a Bug Watch
+==================================
 
 Comments can be imported from remote bugtrackers.
 
diff --git a/lib/lp/bugs/stories/bugwatches/xx-bugwatch-errors.txt b/lib/lp/bugs/stories/bugwatches/xx-bugwatch-errors.txt
index ba403de..2501411 100644
--- a/lib/lp/bugs/stories/bugwatches/xx-bugwatch-errors.txt
+++ b/lib/lp/bugs/stories/bugwatches/xx-bugwatch-errors.txt
@@ -1,4 +1,5 @@
-= Displaying Bug Watch Errors to the User =
+Displaying Bug Watch Errors to the User
+=======================================
 
 If an error occurs when importing the remote status of a bug that is
 being watched in Launchpad that error will be displayed to users.
diff --git a/lib/lp/bugs/stories/cve/xx-cve-link-xss.txt b/lib/lp/bugs/stories/cve/xx-cve-link-xss.txt
index 96b75a0..8676508 100644
--- a/lib/lp/bugs/stories/cve/xx-cve-link-xss.txt
+++ b/lib/lp/bugs/stories/cve/xx-cve-link-xss.txt
@@ -1,4 +1,5 @@
-== Cross-Site Scripting, or XSS ==
+Cross-Site Scripting, or XSS
+----------------------------
 
 The CVE Sequence Number field and its related messages are properly
 escaped in order to prevent XSS.
diff --git a/lib/lp/bugs/stories/feeds/xx-bug-atom.txt b/lib/lp/bugs/stories/feeds/xx-bug-atom.txt
index b36d6c8..a71dfc5 100644
--- a/lib/lp/bugs/stories/feeds/xx-bug-atom.txt
+++ b/lib/lp/bugs/stories/feeds/xx-bug-atom.txt
@@ -1,4 +1,5 @@
-= Atom Feeds =
+Atom Feeds
+==========
 
 Atom feeds produce XML not HTML.  Therefore we must parse the output as XML
 by asking BeautifulSoup to use lxml.
@@ -17,7 +18,8 @@ will arrange the entries in a different sort order based on the update
 time.
 
 
-== Latest bugs for a product ==
+Latest bugs for a product
+-------------------------
 
 This feed gets the latest bugs reported against a product. The feed
 includes summary information about the bugs such as ID, title, author,
@@ -77,7 +79,8 @@ The Atom feed must have the content-type of "application/atom+xml".
     >>> browser.headers['content-type']
     'application/atom+xml;charset=utf-8'
 
-== Latest bugs for a project ==
+Latest bugs for a project
+-------------------------
 
 This feed gets the latest bugs for a project, and has the same type of content
 as the latest bugs feed for a product.
@@ -138,7 +141,8 @@ Ensure the entries are in reverse chronological order by published date.
     >>> assert check_entries_order(entries), (
     ...     "Published dates are not sorted.")
 
-== Latest bugs for a distro ==
+Latest bugs for a distro
+------------------------
 
 This feed gets the latest bugs for a distribution, and has the same type
 of content as the latest bugs feed for a product.
@@ -176,7 +180,8 @@ of content as the latest bugs feed for a product.
     >>> assert check_entries_order(entries), (
     ...     "Published dates are not sorted.")
 
-=== Private teams as assignees ===
+Private teams as assignees
+..........................
 
 Create a private team and assign an ubuntu distro bug to that team.
 
@@ -222,7 +227,8 @@ Private teams should show as '-'.
     -
     -
 
-== Latest bugs for a source package ==
+Latest bugs for a source package
+--------------------------------
 
 This feed gets the latest bugs for a source package, and has the same
 type of content as the latest bugs feed for a product.
@@ -255,7 +261,8 @@ type of content as the latest bugs feed for a product.
     ...     "Published dates are not sorted.")
 
 
-== Latest bugs for a distroseries ==
+Latest bugs for a distroseries
+------------------------------
 
 This feed gets the latest bugs for a distribution series, and has the same
 type of content as the latest bugs feed for a product.
@@ -295,7 +302,8 @@ type of content as the latest bugs feed for a product.
     ...     "Published dates are not sorted.")
 
 
-== Latest bugs for a product series ==
+Latest bugs for a product series
+--------------------------------
 
 This feed gets the latest bugs for a product series, and has the same
 type of content as the latest bugs feed for a product.
@@ -335,7 +343,8 @@ type of content as the latest bugs feed for a product.
     ...     "Published dates are not sorted.")
 
 
-== Latest bugs for a person ==
+Latest bugs for a person
+------------------------
 
 This feed gets the latest bugs for a person.
 
@@ -381,7 +390,8 @@ This feed gets the latest bugs for a person.
     ...     "Published dates are not sorted.")
 
 
-== Latest bugs for a team ==
+Latest bugs for a team
+----------------------
 
 This feed gets the latest bugs for a whole team.
 First, make a team responsible for some bugs.
@@ -438,7 +448,8 @@ some results.
     ...     "Published dates are not sorted.")
 
 
-== Latest bugs for any target ==
+Latest bugs for any target
+--------------------------
 
 This feed gets the latest bugs reported against any target.
 
@@ -476,7 +487,8 @@ This feed gets the latest bugs reported against any target.
     ...     "Published dates are not sorted.")
 
 
-== General bug search ==
+General bug search
+------------------
 
 This feed is the most useful of them all. Any bug search can be turned into
 a feed.
@@ -550,7 +562,8 @@ to True.
     http://bugs.launchpad.test/~name12
 
 
-== Results for a single bug ==
+Results for a single bug
+------------------------
 
 This feed shows the status of a single bug.
 
@@ -570,7 +583,8 @@ This feed shows the status of a single bug.
     ...     print(link)
     <link href="http://feeds.launchpad.test/bugs/1/bug.atom" rel="self"/>
 
-== Feeds Configuration Options ==
+Feeds Configuration Options
+---------------------------
 
 The max_bug_feed_cache_minutes configuration is provided to allow
 overriding the Expires and Cache-Control headers so that the feeds
diff --git a/lib/lp/bugs/stories/feeds/xx-bug-html.txt b/lib/lp/bugs/stories/feeds/xx-bug-html.txt
index 3b6a6c1..782b8f2 100644
--- a/lib/lp/bugs/stories/feeds/xx-bug-html.txt
+++ b/lib/lp/bugs/stories/feeds/xx-bug-html.txt
@@ -1,4 +1,5 @@
-= HTML Feeds =
+HTML Feeds
+==========
 
 HTML feeds produce snippets of html for inclusion in user's own web pages.
 The content of an HTML feed is very similar to an Atom feed, but is formatted
@@ -40,7 +41,8 @@ And two for printing the results:
     ...     return bug_numbers
 
 
-== Latest bugs for a product ==
+Latest bugs for a product
+-------------------------
 
 This feed gets the latest bugs reported against a product. The feed includes
 summary information about the bugs such as ID, title, author, and a link to
@@ -67,7 +69,8 @@ the bug itself.
     >>> get_bug_numbers(entries)
     [12, 11]
 
-== Latest bugs for a project ==
+Latest bugs for a project
+-------------------------
 
 This feed gets the latest bugs for a project, and has the same type of content
 as the latest bugs feed for a product.
@@ -93,7 +96,8 @@ as the latest bugs feed for a product.
     >>> get_bug_numbers(entries)
     [15, 15, 9, 9, 5, 5, 5, 4, 1, 1, 1]
 
-=== Private teams as assignees ===
+Private teams as assignees
+..........................
 
 Create a private team and assign a mozilla bug to that team.
 
@@ -121,7 +125,8 @@ Get the mozilla/latest-bugs feed. The previous bug should be included.
     >>> get_bug_numbers(entries)
     [15, 15, 9, 9, 5, 5, 5, 4, 1, 1, 1]
 
-== Latest bugs for a person ==
+Latest bugs for a person
+------------------------
 
 This feed gets the latest bugs for a person.
 
@@ -147,7 +152,8 @@ This feed gets the latest bugs for a person.
     [15, 15, 12, 11, 10, 9, 9, 7, 7, 3, 3, 3, 2, 2, 2, 2, 2, 1, 1, 1]
 
 
-== Latest bugs for any target ==
+Latest bugs for any target
+--------------------------
 
 This feed gets the latest bugs reported against any target.
 
@@ -174,7 +180,8 @@ This feed gets the latest bugs reported against any target.
      2, 1, 1, 1]
 
 
-== General bug search ==
+General bug search
+------------------
 
 This feed is the most useful of them all. Any bug search can be turned into
 a feed.
diff --git a/lib/lp/bugs/stories/guided-filebug/xx-distro-guided-filebug-tags.txt b/lib/lp/bugs/stories/guided-filebug/xx-distro-guided-filebug-tags.txt
index 48b4589..52aa4ef 100644
--- a/lib/lp/bugs/stories/guided-filebug/xx-distro-guided-filebug-tags.txt
+++ b/lib/lp/bugs/stories/guided-filebug/xx-distro-guided-filebug-tags.txt
@@ -1,4 +1,5 @@
-= Adding tags when filing bugs =
+Adding tags when filing bugs
+============================
 
 Even though there's no input field for adding tags on the normal
 +filebug page, it's still possible to add tags to filed bugs on that
diff --git a/lib/lp/bugs/stories/guided-filebug/xx-distro-guided-filebug.txt b/lib/lp/bugs/stories/guided-filebug/xx-distro-guided-filebug.txt
index f835994..3755680 100644
--- a/lib/lp/bugs/stories/guided-filebug/xx-distro-guided-filebug.txt
+++ b/lib/lp/bugs/stories/guided-filebug/xx-distro-guided-filebug.txt
@@ -1,4 +1,5 @@
-= Filing bugs on Distributions =
+Filing bugs on Distributions
+============================
 
 Like filing bugs on products, filing bugs on distributions involves
 first finding out if you're bug has already been reported.
@@ -73,7 +74,8 @@ Finally, let's submit the bug.
     http://bugs.launchpad.test/ubuntu/+source/mozilla-firefox/+bug/...
 
 
-== Filing a bug when there are none similar ==
+Filing a bug when there are none similar
+----------------------------------------
 
 When no similar bugs are found the form works the same but appears
 different in the user agent.
diff --git a/lib/lp/bugs/stories/guided-filebug/xx-filebug-attachments.txt b/lib/lp/bugs/stories/guided-filebug/xx-filebug-attachments.txt
index 4843c14..ac1f245 100644
--- a/lib/lp/bugs/stories/guided-filebug/xx-filebug-attachments.txt
+++ b/lib/lp/bugs/stories/guided-filebug/xx-filebug-attachments.txt
@@ -1,11 +1,13 @@
-= Adding attachments when filing a bug =
+Adding attachments when filing a bug
+====================================
 
 It is possible to add attachments when filing a bug. The tests in this
 file will cover this functionality for both the guided and advanced
 filebug forms.
 
 
-== Guided filebug form ==
+Guided filebug form
+-------------------
 
 Adding an attachment to a new bug is part of the second step of the
 guided filebug form.
@@ -50,7 +52,8 @@ No Privileges Person can see the attachment in the attachments portlet.
     'http://bugs.launchpad.test/firefox/+bug/.../+attachment/.../+files/ex...'
 
 
-== Empty Attachment Fields ==
+Empty Attachment Fields
+-----------------------
 
 Sometimes browsers submit values empty fields, leading them to being
 treated as non-empty by the receiving view. The attachment form will
diff --git a/lib/lp/bugs/stories/guided-filebug/xx-filebug-tags.txt b/lib/lp/bugs/stories/guided-filebug/xx-filebug-tags.txt
index f01789f..94d1640 100644
--- a/lib/lp/bugs/stories/guided-filebug/xx-filebug-tags.txt
+++ b/lib/lp/bugs/stories/guided-filebug/xx-filebug-tags.txt
@@ -1,7 +1,9 @@
-= Adding tags =
+Adding tags
+===========
 
 
-== Normal bug filing page ==
+Normal bug filing page
+----------------------
 
 On the normal +filebug page, tags can be added to the bug as the bug
 is being filed.
@@ -25,7 +27,8 @@ is being filed.
     unofficial-tag foo
 
 
-== Pre-populating the tags field ==
+Pre-populating the tags field
+-----------------------------
 
 For people wanting to pre-fill the tags field with certain tags, it's
 possible to do so by supplying a 'field.tags' URL parameter.
diff --git a/lib/lp/bugs/stories/guided-filebug/xx-options-for-bug-supervisors.txt b/lib/lp/bugs/stories/guided-filebug/xx-options-for-bug-supervisors.txt
index f5d8da2..ed42952 100644
--- a/lib/lp/bugs/stories/guided-filebug/xx-options-for-bug-supervisors.txt
+++ b/lib/lp/bugs/stories/guided-filebug/xx-options-for-bug-supervisors.txt
@@ -1,4 +1,5 @@
-= Bug filing options for bug supervisors =
+Bug filing options for bug supervisors
+======================================
 
 During the bug filing process, normal or advanced, bug supervisors are
 able to set the status and importance of the bug being filed, can
@@ -55,7 +56,8 @@ Users who are bug supervisors can see these options:
     <Control name='field.assignee' type='text'>
 
 
-== Using these extra options ==
+Using these extra options
+-------------------------
 
     >>> from lp.bugs.tests.bug import print_bug_affects_table
 
diff --git a/lib/lp/bugs/stories/guided-filebug/xx-productseries-guided-filebug.txt b/lib/lp/bugs/stories/guided-filebug/xx-productseries-guided-filebug.txt
index 699005f..af6d155 100644
--- a/lib/lp/bugs/stories/guided-filebug/xx-productseries-guided-filebug.txt
+++ b/lib/lp/bugs/stories/guided-filebug/xx-productseries-guided-filebug.txt
@@ -1,4 +1,5 @@
-= Filing a bug from the product series page =
+Filing a bug from the product series page
+=========================================
 
 The product series Bugs frontpage includes a link to report a bug.
 
diff --git a/lib/lp/bugs/stories/guided-filebug/xx-sorting-by-relevance.txt b/lib/lp/bugs/stories/guided-filebug/xx-sorting-by-relevance.txt
index 994b4d1..f021320 100644
--- a/lib/lp/bugs/stories/guided-filebug/xx-sorting-by-relevance.txt
+++ b/lib/lp/bugs/stories/guided-filebug/xx-sorting-by-relevance.txt
@@ -1,4 +1,5 @@
-= Sorting the similar bugs found by relevance =
+Sorting the similar bugs found by relevance
+===========================================
 
 When displaying the similar bugs, we display only a small number, even
 though the search usually returns a huge number of results. For this
diff --git a/lib/lp/bugs/stories/upstream-bugprivacy/xx-upstream-bug-privacy.txt b/lib/lp/bugs/stories/upstream-bugprivacy/xx-upstream-bug-privacy.txt
index cbc2de2..00bea23 100644
--- a/lib/lp/bugs/stories/upstream-bugprivacy/xx-upstream-bug-privacy.txt
+++ b/lib/lp/bugs/stories/upstream-bugprivacy/xx-upstream-bug-privacy.txt
@@ -62,7 +62,8 @@ bug listing.
     ...<div class="importance importanceUNDECIDED"> Undecided </div>...
     ...<span class="bugnumber">#BUG-ID</span>...
 
-== Checking basic access to the private bug pages ==
+Checking basic access to the private bug pages
+----------------------------------------------
 
 Trying to access the task edit page of a task on a private bug
 fails, because we pretend that inaccessible private bugs do not exist.
diff --git a/lib/lp/bugs/stories/webservice/xx-bug-target.txt b/lib/lp/bugs/stories/webservice/xx-bug-target.txt
index f4e4c45..6017625 100644
--- a/lib/lp/bugs/stories/webservice/xx-bug-target.txt
+++ b/lib/lp/bugs/stories/webservice/xx-bug-target.txt
@@ -1,10 +1,12 @@
-= Introduction =
+Introduction
+============
 
 Many exposed objects in the API provide IBugTarget, including
 projects, distributions, distribution series, and source packages.
 
 
-== bug_reporting_guidelines ==
+bug_reporting_guidelines
+------------------------
 
 All bug targets have a read/write bug_reporting_guidelines property.
 
@@ -38,7 +40,8 @@ Not everyone can modify it however:
     (<Product at ...>, 'bug_reporting_guidelines', 'launchpad.BugSupervisor')
 
 
-== Official Bug Tags ==
+Official Bug Tags
+-----------------
 
 We can access official bug tag targets and add and remove tags. We
 create a new product, owned by ~salgado.
@@ -138,7 +141,8 @@ We can also access official tags as a list.
     ...     dumps({'official_bug_tags': [u'foo', u'bar']})))
     HTTP/1.1 209 Content Returned...
 
-== bug_supervisor ==
+bug_supervisor
+--------------
 
 We can retrieve or set a person or team as the bug supervisor for projects.
 
diff --git a/lib/lp/bugs/stories/webservice/xx-hide-comments.txt b/lib/lp/bugs/stories/webservice/xx-hide-comments.txt
index dd5510e..8a2a6e1 100644
--- a/lib/lp/bugs/stories/webservice/xx-hide-comments.txt
+++ b/lib/lp/bugs/stories/webservice/xx-hide-comments.txt
@@ -1,4 +1,5 @@
-= Hide bug comments =
+Hide bug comments
+=================
 
 Bug comments can be hidden by setting visible to False.  There is
 a corresponding API method to do this.  Call the method with the
diff --git a/lib/lp/bugs/tests/buglinktarget.txt b/lib/lp/bugs/tests/buglinktarget.txt
index c8c4099..119c94e 100644
--- a/lib/lp/bugs/tests/buglinktarget.txt
+++ b/lib/lp/bugs/tests/buglinktarget.txt
@@ -1,4 +1,5 @@
-= IBugLinkTarget Interface =
+IBugLinkTarget Interface
+========================
 
 Launchpad includes Malone, the powerful bug tracker. One of the best
 features of Malone is the ability to track a bug in multiple products
@@ -22,7 +23,8 @@ shouldn't have any bugs linked to it at the start of the test.)
     >>> verifyObject(IBugLinkTarget, target)
     True
 
-== linkBug() ==
+linkBug()
+---------
 
     >>> bugset = getUtility(IBugSet)
     >>> bug1 = bugset.get(1)
@@ -100,7 +102,8 @@ if they are an administrator:
     >>> target.linkBug(private_bug, admin)
     True
 
-== bugs ==
+bugs
+----
 
 The list of bugs linked to the target should be available in the bugs
 attributes:
@@ -108,7 +111,8 @@ attributes:
     >>> [bug.id for bug in target.bugs]
     [1, 2, 6]
 
-== unlinkBug() ==
+unlinkBug()
+-----------
 
 The unlinkBug() method is used to remove a link between a bug and
 the target.
@@ -169,7 +173,8 @@ the bug or if they are an administrator.
     >>> target.unlinkBug(private_bug, admin)
     True
 
-== Cleanup ==
+Cleanup
+-------
 
     # Unregister event listeners.
     >>> linked_event_listener.cleanUp()
diff --git a/lib/lp/bugs/tests/trac-xmlrpc-transport.txt b/lib/lp/bugs/tests/trac-xmlrpc-transport.txt
index 66de8e7..7f52f95 100644
--- a/lib/lp/bugs/tests/trac-xmlrpc-transport.txt
+++ b/lib/lp/bugs/tests/trac-xmlrpc-transport.txt
@@ -1,4 +1,5 @@
-= TestTracXMLRPCTransport =
+TestTracXMLRPCTransport
+=======================
 
 TestTracXMLRPCTransport is an XML-RPC transport which simulates the LP
 Trac plugin. It can be used to avoid network traffic while testing, and
@@ -26,7 +27,8 @@ some cookie is set.
     >>> trac_transport.setCookie('trac_auth=auth_cookie')
 
 
-== launchpad.bugtracker_version() ==
+launchpad.bugtracker_version()
+------------------------------
 
 bugtracker_version() returns a list of
 [Trac version, plugin version, dupe knowledge]. The version numbers are
@@ -37,7 +39,8 @@ instance knows how to track duplicate bugs.
     ['0.11.0', '1.0', False]
 
 
-== launchpad.time_snapshot() ==
+launchpad.time_snapshot()
+-------------------------
 
 time_snapshot returns information about what the Trac instance thinks
 the current time is. It returns the local time zone, the local time, and
@@ -57,7 +60,8 @@ isn't suitable.
     US/Eastern 1206328061 1206342461
 
 
-== launchpad.bug_info() ==
+launchpad.bug_info()
+--------------------
 
 bug_info() returns, as the name suggests, info about a given bug or set
 of bugs. It takes two parameters: level, an integer indicating how much
@@ -215,7 +219,8 @@ are in the bugs list being returned.
     [{'id': '1'}]
 
 
-== launchpad.get_comments() ==
+launchpad.get_comments()
+------------------------
 
 get_comments() returns a list of comment dicts. The comment dicts
 returned correspond to the comment IDs passed in the comments parameter.
@@ -245,7 +250,8 @@ returned correspond to the comment IDs passed in the comments parameter.
 
 
 
-== launchpad.add_comment() ==
+launchpad.add_comment()
+-----------------------
 
 The Trac XML-RPC API allows us to push comments to remote bug trackers
 via the launchpad.add_comment() method.
@@ -281,7 +287,8 @@ The comment will be included in the remote bug's comments.
     user: launchpad
 
 
-== Getting and setting the Launchpad bug ID ==
+Getting and setting the Launchpad bug ID
+----------------------------------------
 
 The Trac XML-RPC API allows us to tell the remote tracker which
 Launchpad bug links to a particular one of its bugs and also allows us
diff --git a/lib/lp/buildmaster/doc/buildqueue.txt b/lib/lp/buildmaster/doc/buildqueue.txt
index e55c68a..f864ac2 100644
--- a/lib/lp/buildmaster/doc/buildqueue.txt
+++ b/lib/lp/buildmaster/doc/buildqueue.txt
@@ -1,4 +1,5 @@
-= BuildQueue =
+BuildQueue
+==========
 
 BuildQueue class represents the run-time-records of builds being
 processed.
@@ -90,7 +91,8 @@ set 'manual' attribute atomically. For this we use manualScore:
     (True, 1000)
 
 
-== Dispatching and Reseting jobs ==
+Dispatching and Reseting jobs
+-----------------------------
 
 The sampledata contains an active job, being built by the 'bob'
 builder.
@@ -151,7 +153,8 @@ the specified builder.
     BUILDING
 
 
-== BuildQueueSet utility ==
+BuildQueueSet utility
+---------------------
 
 Now perform the tests for the BuildQueue zope utility, BuildQueueSet.
 Check if the instance returned as utility corresponds to its
diff --git a/lib/lp/buildmaster/stories/builder-views.txt b/lib/lp/buildmaster/stories/builder-views.txt
index f93d409..67d5ba3 100644
--- a/lib/lp/buildmaster/stories/builder-views.txt
+++ b/lib/lp/buildmaster/stories/builder-views.txt
@@ -1,4 +1,5 @@
-= Builder View Classes and Pages =
+Builder View Classes and Pages
+==============================
 
     >>> from zope.component import getMultiAdapter, getUtility
     >>> from lp.buildmaster.interfaces.builder import IBuilderSet
@@ -28,7 +29,8 @@ mode button.
     Switch to manual-mode
 
 
-== Builder history ==
+Builder history
+---------------
 
 Let's instantiate a view for +history:
 
@@ -49,7 +51,8 @@ mock_form:
     5
 
 
-== Builder edit ==
+Builder edit
+------------
 
 Let's instantiate the view for +edit and check that the correct title,
 fields and actions are displayed:
@@ -118,7 +121,8 @@ After editing a builder, a relevant notification is added to the view.
     The builder &quot;Bob The Builder&quot; was updated successfully.
 
 
-== Builders building private jobs ==
+Builders building private jobs
+------------------------------
 
 In order to restrict access to private PPA details in general, we also
 need to be able to hide the fact that a builder is building a private
@@ -229,7 +233,8 @@ again.
     >>> login(ANONYMOUS)
 
 
-== BuilderSet view ==
+BuilderSet view
+---------------
 
 BuilderSetView offer a way to treat the currently registered builders
 in categories. They are:
diff --git a/lib/lp/buildmaster/stories/xx-buildfarm-index.txt b/lib/lp/buildmaster/stories/xx-buildfarm-index.txt
index 5ab1e01..16932a5 100644
--- a/lib/lp/buildmaster/stories/xx-buildfarm-index.txt
+++ b/lib/lp/buildmaster/stories/xx-buildfarm-index.txt
@@ -1,4 +1,5 @@
-= BuildFarm page =
+BuildFarm page
+==============
 
 The BuildFarm page is accessible from the root page, although we don't
 link to it yet because we are not yet sure of the benefits of doing
diff --git a/lib/lp/code/doc/branch-karma.txt b/lib/lp/code/doc/branch-karma.txt
index f780602..5b44699 100644
--- a/lib/lp/code/doc/branch-karma.txt
+++ b/lib/lp/code/doc/branch-karma.txt
@@ -1,4 +1,5 @@
-= Karma for branch related activity =
+Karma for branch related activity
+=================================
 
 We want people to register their branches on Launchpad, and also to
 link their branches to bugs and specs, so we give them some karma for
@@ -29,7 +30,8 @@ give karma for it.
     >>> karma_helper = KarmaAssignedEventListener(show_person=True)
     >>> karma_helper.register_listener()
 
-== Registering branches ==
+Registering branches
+--------------------
 
 Karma is added for registering a branch.
 
@@ -44,7 +46,8 @@ However, no karma is added for junk branches.
     >>> junk_branch = factory.makePersonalBranch(owner=eric)
 
 
-== Linking bugs and branches ==
+Linking bugs and branches
+-------------------------
 
 You get karma for linking a bug to a branch.
 
@@ -59,7 +62,8 @@ As long as it is not a junk branch.
     >>> branch_link = bug.linkBranch(junk_branch, eric)
 
 
-== Linking blueprints and branches ==
+Linking blueprints and branches
+-------------------------------
 
 You get karma for linking a blueprint to a branch.
 
diff --git a/lib/lp/code/doc/branch-notifications.txt b/lib/lp/code/doc/branch-notifications.txt
index 00696fe..d59000b 100644
--- a/lib/lp/code/doc/branch-notifications.txt
+++ b/lib/lp/code/doc/branch-notifications.txt
@@ -1,4 +1,5 @@
-= Email Notifications for Branches =
+Email Notifications for Branches
+================================
 
 Only subscribers get email notifications.  If the owner/author of the
 branch wants to receive emails, then they need to subscribe to the
@@ -12,7 +13,8 @@ There are two situations where emails are sent out for branches:
  - when the branch scanner scans new revisions in the branches history
 
 
-== Email Format ==
+Email Format
+------------
 
 All branch notification emails use a standard email template.
 
@@ -77,7 +79,8 @@ also sends the email to the list of recipients.
     >>> branch.unsubscribe(branch.owner, branch.owner)
 
 
-== Subscriptions ==
+Subscriptions
+-------------
 
 When users subscribe to the branch, they specify which branch
 modified events they want to receive email for.  This is one of the
@@ -192,7 +195,8 @@ to allow email filtering.
     [e-mail]                  Send entire diff  Subscriber
 
 
-== Limiting the size of diff received by email ==
+Limiting the size of diff received by email
+-------------------------------------------
 
     # A helper function to print out the To header and
     # email body
@@ -359,7 +363,8 @@ Unsubscribe everybody.
     0
 
 
-== Group subscriptions ==
+Group subscriptions
+-------------------
 
 If a group is subscribed the emails are sent to the members of that team.
 If an individual is also subscribed to the branch, then the setting
@@ -398,7 +403,8 @@ that is used rather than the email addresses of the seven members.
     [e-mail]           1000 lines   Subscriber @ubuntu-team
 
 
-== Attribute emails ==
+Attribute emails
+----------------
 
     # Another helper function to print out the To, From and Subject headers
     # and the email body
@@ -522,7 +528,8 @@ something like this:
     http://code.launchpad.test/~name12/firefox/new-name/+edit-subscription
 
 
-== Unicode in emails ==
+Unicode in emails
+-----------------
 
 All the text fields of a branch are considered unicode, so the email
 must also handle the unicode.
@@ -551,7 +558,8 @@ must also handle the unicode.
     http://code.launchpad.test/~name12/firefox/new-name/+edit-subscription
 
 
-== Modifications by users other than the branch owner ==
+Modifications by users other than the branch owner
+--------------------------------------------------
 
 If another user modified some branch attributes, then an email is sent
 to the branch owner.
diff --git a/lib/lp/code/doc/code-jobs.txt b/lib/lp/code/doc/code-jobs.txt
index 991cca4..732d9d6 100644
--- a/lib/lp/code/doc/code-jobs.txt
+++ b/lib/lp/code/doc/code-jobs.txt
@@ -1,9 +1,11 @@
-= Code Jobs =
+Code Jobs
+=========
 
 The addition of the Job table provides a generic way to have server side jobs
 processing events generated from the web UI.
 
-== Branch Jobs ==
+Branch Jobs
+-----------
 
 This type of job processes events that have been generated for branches.
 
@@ -18,7 +20,8 @@ created.
 The BranchJob table has a json_data field to hold details specific
 to the particular type of subscription job.
 
-=== BranchJobType.REVISION ===
+BranchJobType.REVISION
+......................
 
 The json data would hold:
   from_revno - the first revision number to process
@@ -26,19 +29,22 @@ The json data would hold:
   to_revno - the last revision number to process
   to_revid - the revision id of the to revno
 
-=== BranchJobType.ATTRIBUTE ===
+BranchJobType.ATTRIBUTE
+.......................
 
 The json data would hold the from and to values of the change, and for values
 where we only show the new values, it would hold those too.
 
-=== BranchJobType.IMPORT ===
+BranchJobType.IMPORT
+....................
 
 The json data here would effectively store the text of the message.  Used
 primarily in the status changes on the import job itself.  Perhpas this should
 be combined with the attribute type email and have a general preamble for the
 generated email.
 
-== Branch Merge Proposal Jobs ==
+Branch Merge Proposal Jobs
+--------------------------
 
 Jobs for merge proposals are slightly different from individual branch
 subscription based emails as merge proposal jobs end up sending emails to
@@ -52,22 +58,26 @@ subscribers of both the source and target branches.
 
 Each job also has some optional json data.
 
-=== BranchMergeProposalJobType.NEW ===
+BranchMergeProposalJobType.NEW
+..............................
 
 The json data includes the identity of the initial comment if one was made,
 and the initial reviewer if one was requested.
 
 
-=== BranchMergeProposalJobType.COMMENT ===
+BranchMergeProposalJobType.COMMENT
+..................................
 
 The json data here refers to the identify of the commit message.
 
-=== BranchMergeProposalJobType.NEW_REVIEWER ===
+BranchMergeProposalJobType.NEW_REVIEWER
+.......................................
 
 The json data here refers to the new reviewer and the type of review
 requested.
 
-=== BranchMergeProposalJobType.DIFF_GENERATION ===
+BranchMergeProposalJobType.DIFF_GENERATION
+..........................................
 
 The dynamic moving diff has been determined to be out of date, and a new diff
 needs to be generated.  This is processed by the merge analysis deamon.
diff --git a/lib/lp/code/doc/codeimport-job.txt b/lib/lp/code/doc/codeimport-job.txt
index 0e83ca1..e28e6d8 100644
--- a/lib/lp/code/doc/codeimport-job.txt
+++ b/lib/lp/code/doc/codeimport-job.txt
@@ -1,4 +1,5 @@
-= Code Import Jobs =
+Code Import Jobs
+================
 
 A CodeImportJob is a record of a pending or running code import job.
 
@@ -45,7 +46,8 @@ modified using the CodeImportJobWorkflow utility.
     True
 
 
-== Sample data of interest ==
+Sample data of interest
+-----------------------
 
 There are two CodeImport objects of interest in the sample data.
 
@@ -79,7 +81,8 @@ required to initiate the action.
     >>> nopriv = person_set.getByName('no-priv')
 
 
-== Test helpers ==
+Test helpers
+------------
 
 The NewEvents class helps testing the creation of CodeImportEvent
 objects.
@@ -88,7 +91,8 @@ objects.
     ...     NewEvents)
 
 
-== Testing whether a job is overdue ==
+Testing whether a job is overdue
+--------------------------------
 
 CodeImportJob objects have a date_due attribute that specifies when the
 job should ideally be started. If the date_due is in the past, the job
@@ -129,7 +133,8 @@ current transaction, then the job is overdue.
     True
 
 
-== Creating a new job ==
+Creating a new job
+------------------
 
 CodeImportJob objects are created using the CodeImportJobWorkflow.newJob
 method.
@@ -158,7 +163,8 @@ the date due may be UTC_NOW or a timestamp in the future. This is
 covered in detail in the test_codeimportjob.py file.
 
 
-== Deleting a pending job ==
+Deleting a pending job
+----------------------
 
 In normal use, the only case where a job object is deleted explicitly is
 when the review status of a code import is modified. This case is
@@ -173,7 +179,8 @@ associated job is not running, the job is deleted.
     None
 
 
-== Requesting a job run ==
+Requesting a job run
+--------------------
 
 When a job is pending, users can request that it be run as soon as
 possible.
@@ -213,7 +220,8 @@ another user, present a message explaining that this has happened.
     ~vcs-imports/gnome-terminal/import was already requested by no-priv.
 
 
-== Starting a job ==
+Starting a job
+--------------
 
 When a job is about to performed by a code import worker, the startJob
 workflow method updates the job's fields to indicate that it is now
@@ -235,7 +243,8 @@ The event is also recorded in the CodeImportEvent audit trail.
     START ~vcs-imports/gnome-terminal/import bazaar-importer
 
 
-== Recording progress on a job ==
+Recording progress on a job
+---------------------------
 
 As the code import worker progresses, it calls the updateHeartbeat
 method at least every minute to indicate that it is still progressing.
diff --git a/lib/lp/code/doc/codeimport-result.txt b/lib/lp/code/doc/codeimport-result.txt
index 0e0fc26..402de61 100644
--- a/lib/lp/code/doc/codeimport-result.txt
+++ b/lib/lp/code/doc/codeimport-result.txt
@@ -1,4 +1,5 @@
-= Code Import Results =
+Code Import Results
+===================
 
 A CodeImportResult is a record of a completed code import job.  They
 are accessed via a utility registered for the ICodeImportResultSet
@@ -19,7 +20,8 @@ member of the vcs-imports team and can access the objects freely.
 
     >>> login('[e-mail]')
 
-== Creating CodeImportResults ==
+Creating CodeImportResults
+--------------------------
 
 Creating CodeImportResult objects is usually done by the finishJob()
 method of the CodeImportWorkflow utility, but here we use the object
@@ -85,7 +87,8 @@ A helper property exists to give the duration of the job run.
     4:00:00
 
 
-== Retrieving CodeImportResults ==
+Retrieving CodeImportResults
+----------------------------
 
 The CodeImportResult objects for a given import can be retrieved in
 reverse chronological order with the results attribute on a code import.
diff --git a/lib/lp/code/doc/codereviewcomment.txt b/lib/lp/code/doc/codereviewcomment.txt
index 950915f..8023afd 100644
--- a/lib/lp/code/doc/codereviewcomment.txt
+++ b/lib/lp/code/doc/codereviewcomment.txt
@@ -1,4 +1,5 @@
-= Code review comments =
+Code review comments
+====================
 
 When code is proposed to be merged, it's common to perform a review of
 that code, which is often in the form of a conversation.  The reviewer
@@ -13,7 +14,8 @@ It has an IMessage as a member (in a one-to-one relationship), a vote
 about.
 
 
-== Creating CodeReviewComments ==
+Creating CodeReviewComments
+---------------------------
 
 CodeReviewComments are created from their BranchMergeProposals:
 
@@ -101,7 +103,8 @@ Now run the pending job to send the email.
     True
 
 
-== Interfaces ==
+Interfaces
+----------
 
 The CodeReviewComment must implement the ICodeReviewComment interface.
 
diff --git a/lib/lp/code/doc/revision.txt b/lib/lp/code/doc/revision.txt
index e514d69..054aa34 100644
--- a/lib/lp/code/doc/revision.txt
+++ b/lib/lp/code/doc/revision.txt
@@ -1,10 +1,12 @@
-= Bazaar Revisions =
+Bazaar Revisions
+================
 
 Branches are collection of revisions, and a revision can exist independently
 from any branch. Revisions are created automatically by scanning branches,
 they have no creation interface and Launchpad cannot create or modify them.
 
-== Interfaces ==
+Interfaces
+----------
 
     >>> from lp.services.database.interfaces import IStore
     >>> from lp.testing import verifyObject
@@ -27,7 +29,8 @@ they have no creation interface and Launchpad cannot create or modify them.
     ...     IStore(BranchRevision).find(BranchRevision).any())
     True
 
-== Creating revisions ==
+Creating revisions
+------------------
 
 The creator of a revision is identified by a RevisionAuthor. A RevisionAuthor
 is not a person because that is only an informational attribute, and even if
@@ -61,7 +64,8 @@ while the date_created is the time when the database record was created.
     ...     revision_author=author, revision_id=revision_id_1,
     ...     revision_date=date)
 
-== Parents ==
+Parents
+-------
 
 Bazaar revisions can have multiple parents, the "leftmost" parent is the
 revision that was used as a base when committing, other parents are used to
@@ -78,7 +82,8 @@ we can represent revisions whose at least one parent is a ghost revision.
     >>> rev2_parent = RevisionParent(sequence=0, revision=revision_2,
     ...                              parent_id=revision_1.revision_id)
 
-== Branch ancestry ==
+Branch ancestry
+---------------
 
 Revisions are associated to branches through the BranchRevision table. A given
 revision may appear in different positions in different branches thanks to
@@ -98,7 +103,8 @@ BranchRevision rows are created using `Branch.createBranchRevision`.
     >>> rev_no_1.branch == rev_no_2.branch == branch
     True
 
-=== Accessing BranchRevision ===
+Accessing BranchRevision
+........................
 
     >>> branch = getUtility(IBranchLookup).getByUniqueName(
     ...     '~name12/+junk/junk.contrib')
@@ -161,7 +167,8 @@ history of the branch.
     foo@localhost-20051031170357-1301ad6d387feb23
 
 
-=== Deleting BranchRevisions ===
+Deleting BranchRevisions
+........................
 
 If a branch gets overwritten or some revisions get uncommitted,
 Launchpad's view of the branch will differ from the actual state of the
@@ -211,7 +218,8 @@ may be referenced by some other branch):
     foo@localhost-20051031170357-1301ad6d387feb23
 
 
-== IRevisionSet.new() ==
+IRevisionSet.new()
+------------------
 
 Revision objects can be created using the IRevisionSet utility.
 Associated RevisionAuthor and RevisionParent objects will be created
diff --git a/lib/lp/code/stories/branches/package-branch-merge-proposals.txt b/lib/lp/code/stories/branches/package-branch-merge-proposals.txt
index aa63f94..298659e 100644
--- a/lib/lp/code/stories/branches/package-branch-merge-proposals.txt
+++ b/lib/lp/code/stories/branches/package-branch-merge-proposals.txt
@@ -1,4 +1,5 @@
-= Package branch merge proposals =
+Package branch merge proposals
+==============================
 
 Package branches can be used for merge proposals just like normal upstream
 branches.
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 fd71f6a..9dfe4e0 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
@@ -1,4 +1,5 @@
-= Package branch merging with product branches =
+Package branch merging with product branches
+============================================
 
 If the source package is linked to the product, then package branches for that
 source package are allowed to be proposed for merging into product branches
diff --git a/lib/lp/code/stories/branches/xx-branch-listings-merge-proposal-badge.txt b/lib/lp/code/stories/branches/xx-branch-listings-merge-proposal-badge.txt
index ce25e5c..63ab38c 100644
--- a/lib/lp/code/stories/branches/xx-branch-listings-merge-proposal-badge.txt
+++ b/lib/lp/code/stories/branches/xx-branch-listings-merge-proposal-badge.txt
@@ -1,4 +1,5 @@
-= Check if the merge proposal badge is shown =
+Check if the merge proposal badge is shown
+==========================================
 
     >>> def branchSummary(browser):
     ...     table = find_tag_by_id(browser.contents, 'branchtable')
diff --git a/lib/lp/code/stories/branches/xx-branch-listings.txt b/lib/lp/code/stories/branches/xx-branch-listings.txt
index b1e0399..1df95ae 100644
--- a/lib/lp/code/stories/branches/xx-branch-listings.txt
+++ b/lib/lp/code/stories/branches/xx-branch-listings.txt
@@ -1,4 +1,5 @@
-= Branch Listing Pages =
+Branch Listing Pages
+====================
 
 Pages that want to display lists of branches use the branch-listing
 page template, and views derived from BranchListingView.
@@ -12,7 +13,8 @@ various kinds and badge decoration.
     >>> reset_all_branch_last_modified()
 
 
-== Branch Batching ==
+Branch Batching
+---------------
 
 Batching is applied to branch listings where there are many items.
 Luckily for us, many is 5 in the tests.
@@ -73,7 +75,8 @@ needed, then the table is sortable and no batching navigation links are shown.
     True
 
 
-== Lifecycle Filtering for Person Branches ==
+Lifecycle Filtering for Person Branches
+---------------------------------------
 
 When the branches for a person is first loaded, only the 'Current' branches
 are shown.  Current branches are those that have a lifecycle status of
@@ -206,7 +209,8 @@ first.
 
 
 
-== Branch Badge Decoration ==
+Branch Badge Decoration
+-----------------------
 
 We display badges for associated bugs.
 
@@ -268,7 +272,8 @@ Now the badge is still shown for Sample Person...
       Linked to a bug
 
 
-== Sorting Branch Listings ==
+Sorting Branch Listings
+-----------------------
 
 Aside from the implicitly sorted listings of recently registered,
 imported and changed branches, all branch listings have a widget that
@@ -361,7 +366,8 @@ Finally, sorting by a particular criterion has the desired effect.
     lp://dev/~name12/gnome-terminal/mirrored        Development             ...
 
 
-== Highlighting the development focus branch ==
+Highlighting the development focus branch
+-----------------------------------------
 
 The branch associated with the development focus series is highlighted
 on the branch listings using the same CSS style that is used to
@@ -415,7 +421,8 @@ The current development focus is shown first though.
     lp://dev/gnome-terminal  Series: trunk, alpha, pre-1.0  ...
 
 
-== Lifecycle Filtering for Product Branches ==
+Lifecycle Filtering for Product Branches
+----------------------------------------
 
 When the branches for a product are first loaded, only the 'Current'
 branches are shown.  Current branches are those that have a
@@ -464,7 +471,8 @@ first.
     lp://dev/gnome-terminal   Series: trunk...    Development  ...
 
 
-== The last commit ==
+The last commit
+---------------
 
 The last commit column shows the revision number, and part of the
 revision log for the last commit that Launchpad knows about.  The
diff --git a/lib/lp/code/stories/branches/xx-branch-mirror-failures.txt b/lib/lp/code/stories/branches/xx-branch-mirror-failures.txt
index ac1ce8b..47b2a43 100644
--- a/lib/lp/code/stories/branches/xx-branch-mirror-failures.txt
+++ b/lib/lp/code/stories/branches/xx-branch-mirror-failures.txt
@@ -1,4 +1,5 @@
-= Branch mirror failure messages =
+Branch mirror failure messages
+==============================
 
 If a branch fails to mirror, that information is displayed in the mirror's
 page, together with the last failure message we got when mirroring.
@@ -160,7 +161,8 @@ display any failure-related information.
     None
 
 
-== Errors for ssh protocols ==
+Errors for ssh protocols
+------------------------
 
 If a branch has a sftp or bzr+ssh URL, immediately display an error message
 (even before mirroring is attempted) and do not display the mirror failure
@@ -182,7 +184,8 @@ or passwords, neither of which is currently supported.
     Launchpad cannot mirror this branch because its URL uses sftp or bzr+ssh.
 
 
-== Remote branches don't error on ssh access ==
+Remote branches don't error on ssh access
+-----------------------------------------
 
 If a remote branch specifies a location with the scheme 'sftp' or 'bzr+ssh'
 then there is no error shown.
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 3cded73..41f91b3 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
@@ -1,4 +1,5 @@
-= Claiming Team Code Reviews =
+Claiming Team Code Reviews
+==========================
 
 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]"
diff --git a/lib/lp/code/stories/branches/xx-distribution-branches.txt b/lib/lp/code/stories/branches/xx-distribution-branches.txt
index b5d0038..fe2cde8 100644
--- a/lib/lp/code/stories/branches/xx-distribution-branches.txt
+++ b/lib/lp/code/stories/branches/xx-distribution-branches.txt
@@ -1,4 +1,5 @@
-= Branch listings for distributions =
+Branch listings for distributions
+=================================
 
 All source package branches are associated with a distribution series, and
 hence a distribution.
diff --git a/lib/lp/code/stories/branches/xx-distroseries-branches.txt b/lib/lp/code/stories/branches/xx-distroseries-branches.txt
index adebd1e..e80ff33 100644
--- a/lib/lp/code/stories/branches/xx-distroseries-branches.txt
+++ b/lib/lp/code/stories/branches/xx-distroseries-branches.txt
@@ -1,4 +1,5 @@
-= Branch listings for distroseries =
+Branch listings for distroseries
+================================
 
 All source package branches are associated with a distribution series and a
 source package name.
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 b9886ed..c071545 100644
--- a/lib/lp/code/stories/branches/xx-person-portlet-teambranches.txt
+++ b/lib/lp/code/stories/branches/xx-person-portlet-teambranches.txt
@@ -1,4 +1,5 @@
-= Person Team Branches Portlet =
+Person Team Branches Portlet
+============================
 
 The purpose of this portlet is to indiciate that there are teams
 that this person participates in that has branches.
diff --git a/lib/lp/code/stories/branches/xx-product-overview.txt b/lib/lp/code/stories/branches/xx-product-overview.txt
index 7f9b8dd..28588f0 100644
--- a/lib/lp/code/stories/branches/xx-product-overview.txt
+++ b/lib/lp/code/stories/branches/xx-product-overview.txt
@@ -1,4 +1,5 @@
-== Latest branches ==
+Latest branches
+---------------
 
 On the product overview page there is a portlet to show recently
 registered branches.
diff --git a/lib/lp/code/stories/branches/xx-source-package-branches-empty.txt b/lib/lp/code/stories/branches/xx-source-package-branches-empty.txt
index b38fe32..70b29f4 100644
--- a/lib/lp/code/stories/branches/xx-source-package-branches-empty.txt
+++ b/lib/lp/code/stories/branches/xx-source-package-branches-empty.txt
@@ -1,4 +1,5 @@
-= Empty source package branch listings =
+Empty source package branch listings
+====================================
 
 When you look at an empty source package branch listing, you see some nice,
 helpful text.
diff --git a/lib/lp/code/stories/branches/xx-source-package-branches-listing.txt b/lib/lp/code/stories/branches/xx-source-package-branches-listing.txt
index 7f8a8f7..a90c1e9 100644
--- a/lib/lp/code/stories/branches/xx-source-package-branches-listing.txt
+++ b/lib/lp/code/stories/branches/xx-source-package-branches-listing.txt
@@ -1,4 +1,5 @@
-= Populated source package branch listings =
+Populated source package branch listings
+========================================
 
 Going to a source package branch page shows a list of branches.
 
diff --git a/lib/lp/code/stories/branches/xx-upload-directions.txt b/lib/lp/code/stories/branches/xx-upload-directions.txt
index bbe8717..4e894dd 100644
--- a/lib/lp/code/stories/branches/xx-upload-directions.txt
+++ b/lib/lp/code/stories/branches/xx-upload-directions.txt
@@ -1,4 +1,5 @@
-= Directions to upload to branches =
+Directions to upload to branches
+================================
 
 The branch ~name12/gnome-terminal/pushed is an upload branch. Its index page
 shows contextual directions on how to upload to it.
@@ -41,7 +42,8 @@ We will also need a ssh key. Save it now.
     ...     '8nAA7z21wAukvE1Pl6AQyG0e7U1sYS8Pc8dtmzJvdtVZWBl02/gqQJ7f06mFvn'
     ...     'sN45rR1Uyxnrwl6rbFwqabZDlyD5Ac6Icbvz9SG1gBOiI= andrew@trogdor')
 
-== Branch owned by a person ==
+Branch owned by a person
+------------------------
 
 Initially, the user is not logged in, the branch page points to the owner of
 the branch, and suggest logging in for directions.
@@ -79,7 +81,8 @@ URL for the branch.
     bzr push --use-existing-dir lp://dev/~name12/gnome-terminal/pushed
 
 
-== SSH key directions ==
+SSH key directions
+------------------
 
 If the user has the permission to upload to a branch, but does not have an SSH
 key registered, point to the SSH keys form.
@@ -129,7 +132,8 @@ appear.
     None
 
 
-== Branch owned by a team ==