[1.4.x] Fixed #19756 - Corrected a ManyToMany example and added some links and markup.

Backport of 43efefae69 from master

docs/topics/db/examples/many_to_many.txt

@@ -35,7 +35,7 @@ objects, and a ``Publication`` has multiple ``Article`` objects:
 What follows are examples of operations that can be performed using the Python
 API facilities.
 
-Create a couple of Publications::
+Create a couple of ``Publications``::
 
     >>> p1 = Publication(title='The Python Journal')
     >>> p1.save()
@@ -44,11 +44,11 @@ Create a couple of Publications::
     >>> p3 = Publication(title='Science Weekly')
     >>> p3.save()
 
-Create an Article::
+Create an ``Article``::
 
     >>> a1 = Article(headline='Django lets you build Web apps easily')
 
-You can't associate it with a Publication until it's been saved::
+You can't associate it with a ``Publication`` until it's been saved::
 
     >>> a1.publications.add(p1)
     Traceback (most recent call last):
@@ -60,11 +60,11 @@ Save it!
 
     >>> a1.save()
 
-Associate the Article with a Publication::
+Associate the ``Article`` with a ``Publication``::
 
     >>> a1.publications.add(p1)
 
-Create another Article, and set it to appear in both Publications::
+Create another ``Article``, and set it to appear in both ``Publications``::
 
     >>> a2 = Article(headline='NASA uses Python')
     >>> a2.save()
@@ -75,25 +75,26 @@ Adding a second time is OK::
 
     >>> a2.publications.add(p3)
 
-Adding an object of the wrong type raises TypeError::
+Adding an object of the wrong type raises :exc:`~exceptions.TypeError`::
 
     >>> a2.publications.add(a1)
     Traceback (most recent call last):
     ...
     TypeError: 'Publication' instance expected
 
-Add a Publication directly via publications.add by using keyword arguments::
+Create and add a ``Publication`` to an ``Article`` in one step using
+:meth:`~django.db.models.fields.related.RelatedManager.create`::
 
     >>> new_publication = a2.publications.create(title='Highlights for Children')
 
-Article objects have access to their related Publication objects::
+``Article`` objects have access to their related ``Publication`` objects::
 
     >>> a1.publications.all()
     [<Publication: The Python Journal>]
     >>> a2.publications.all()
     [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
 
-Publication objects have access to their related Article objects::
+``Publication`` objects have access to their related ``Article`` objects::
 
     >>> p2.article_set.all()
     [<Article: NASA uses Python>]
@@ -102,7 +103,8 @@ Publication objects have access to their related Article objects::
     >>> Publication.objects.get(id=4).article_set.all()
     [<Article: NASA uses Python>]
 
-Many-to-many relationships can be queried using :ref:`lookups across relationships <lookups-that-span-relationships>`::
+Many-to-many relationships can be queried using :ref:`lookups across
+relationships <lookups-that-span-relationships>`::
 
     >>> Article.objects.filter(publications__id__exact=1)
     [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
@@ -119,7 +121,8 @@ Many-to-many relationships can be queried using :ref:`lookups across relationshi
     >>> Article.objects.filter(publications__title__startswith="Science").distinct()
     [<Article: NASA uses Python>]
 
-The count() function respects distinct() as well::
+The :meth:`~django.db.models.query.QuerySet.count` function respects
+:meth:`~django.db.models.query.QuerySet.distinct` as well::
 
     >>> Article.objects.filter(publications__title__startswith="Science").count()
     2
@@ -133,7 +136,7 @@ The count() function respects distinct() as well::
     [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
 
 Reverse m2m queries are supported (i.e., starting at the table that doesn't have
-a ManyToManyField)::
+a :class:`~django.db.models.ManyToManyField`)::
 
     >>> Publication.objects.filter(id__exact=1)
     [<Publication: The Python Journal>]
@@ -163,7 +166,7 @@ involved is a little complex)::
     >>> Article.objects.exclude(publications=p2)
     [<Article: Django lets you build Web apps easily>]
 
-If we delete a Publication, its Articles won't be able to access it::
+If we delete a ``Publication``, its ``Articles`` won't be able to access it::
 
     >>> p1.delete()
     >>> Publication.objects.all()
@@ -172,7 +175,7 @@ If we delete a Publication, its Articles won't be able to access it::
     >>> a1.publications.all()
     []
 
-If we delete an Article, its Publications won't be able to access it::
+If we delete an ``Article``, its ``Publications`` won't be able to access it::
 
     >>> a2.delete()
     >>> Article.objects.all()
@@ -199,7 +202,7 @@ Adding via the other end using keywords::
     >>> a5.publications.all()
     [<Publication: Science News>]
 
-Removing publication from an article::
+Removing ``Publication`` from an ``Article``::
 
     >>> a4.publications.remove(p2)
     >>> p2.article_set.all()
@@ -242,7 +245,7 @@ And you can clear from the other end::
     >>> p2.article_set.all()
     [<Article: Oxygen-free diet works wonders>]
 
-Recreate the article and Publication we have deleted::
+Recreate the ``Article`` and ``Publication`` we have deleted::
 
     >>> p1 = Publication(title='The Python Journal')
     >>> p1.save()
@@ -250,7 +253,8 @@ Recreate the article and Publication we have deleted::
     >>> a2.save()
     >>> a2.publications.add(p1, p2, p3)
 
-Bulk delete some Publications - references to deleted publications should go::
+Bulk delete some ``Publications`` - references to deleted publications should
+go::
 
     >>> Publication.objects.filter(title__startswith='Science').delete()
     >>> Publication.objects.all()
@@ -267,15 +271,18 @@ Bulk delete some articles - references to deleted objects should go::
     [<Article: Django lets you build Web apps easily>]
     >>> q.delete()
 
-After the delete, the QuerySet cache needs to be cleared, and the referenced
-objects should be gone::
+After the :meth:`~django.db.models.query.QuerySet.delete`, the
+:class:`~django.db.models.query.QuerySet` cache needs to be cleared, and the
+referenced objects should be gone::
 
     >>> print q
     []
     >>> p1.article_set.all()
     [<Article: NASA uses Python>]
 
-An alternate to calling clear() is to assign the empty set::
+An alternate to calling
+:meth:`~django.db.models.fields.related.RelatedManager.clear` is to assign the
+empty set::
 
     >>> p1.article_set = []
     >>> p1.article_set.all()