WiP: Improving documentation

docs/reference/catalog.rst

@@ -171,7 +171,7 @@ For this purpose, we have to declare a product summary serializer using the conf
 product must offer, it's up to the merchant to declare this product summary serializer as well.
 A typical implementation might look like:
 
-.. code-block::
+.. code-block:: python
 
 	class ProductSummarySerializer(ProductSerializer):
 	    media = serializers.SerializerMethodField(

docs/reference/money-types.rst

@@ -15,7 +15,7 @@ it is very common to make mistakes by mixing different currencies. It also is co
 incorrect conversions that generate wrong results. Python doesn't allow developers to associate a
 specific decimal value with a unit.
 
-Starting with version 0.9, **django-SHOP** is shipped with a special factory class:
+Starting with version 0.9, **django-SHOP** ships with a special factory class:
 
 
 MoneyMaker
@@ -32,8 +32,8 @@ Not a Number
 
 In special occurrences we'd rather want to specify "no amount" rather than an amount of 0.00 (zero).
 This can be useful for free samples, or when an item currently is not available. The Decimal type
-denotes a kind of special value a ``NaN`` – for "Not a Number". Our Money type also knows about
-this special value, and when rendered, ``€ –`` or ``$ –```` is printed out.
+denotes a kind of special value a ``NaN`` – for "Not a Number". Our Money type therefore inherits
+this special value, but renders it for instance as ``€ –`` or ``$ –``.
 
 Declaring a Money object without a value, say ``m = Money()`` creates such a special value. The big
 difference as for the ``Decimal`` type is that when adding or subtracting a ``NaN`` to a valid

docs/reference/payment-providers.rst

@@ -33,12 +33,13 @@ shop site.
 Therefore other PSPs allow to create form elements in HTML, whose content is send to their site
 during the purchase task. This can be done using a POST submission, followed by a redirection back
 to the client. Other providers use Javascript for submission and return a payment token to the
-customer, who himself forwards that token to the shopping site.
+customer, which itself forwards that token to the shopping site.
 
-All in all, there are so many different ways to pay, that it is quite tricky to find a generic
-solution compatible for all of them.
+All in all, there are so many different ways to do online payment, that it is quite tricky to find
+a generic solution compatible for all of them.
 
-Here **django-SHOP** uses some Javascript during the purchase operation. Lets explain how:
+In **django-SHOP**, we can add some Javascript specific to the PSP's needs, which is used during the
+purchase operation. Let's explain how it works:
 
 
 .. _reference/the-purchasing-operation:
@@ -57,28 +58,31 @@ It may look similar to this::
 Whenever the customer clicks onto that button, the function ``proceedWith('PURCHASE_NOW')`` is
 invoked in the scope of the AngularJS controller, belonging to the given directive.
 
-This function first uploads the current checkout forms to the server. There they are validated, and
-if everything is OK, an updated checkout context is send back to the client. See
-:class:`shop.views.checkout.CheckoutViewSet.upload()` for details.
+This function first uploads the current checkout forms to the server. There the form is validated,
+and if everything is OK, an updated checkout context is send back to the client. For implementation
+details, have a look at the endpoint at :meth:`shop.views.checkout.CheckoutViewSet.upload()`.
 
 Next, the success handler of the previous submission looks at the given action. In ``proceedWith``,
 we used the magic keyword ``PURCHASE_NOW``, which starts a second submission to the server,
-requesting to begin with the purchase operation (See :class:`shop.views.checkout.CheckoutViewSet.purchase()`
-for details.). This method determines he payment provider previously chosen by the customer. It
-then invokes the method ``get_payment_request()`` of that provider, which returns a Javascript
-expression.
+requesting to begin with the purchase operation (see
+:meth:`shop.views.checkout.CheckoutViewSet.purchase()` for details.). This method determines the
+payment provider previously chosen by the customer. It then invokes the method
+``get_payment_request()`` of that provider, which returns a Javascript expression.
 
 On the client, this returned Javascript expression is passed to the `eval()`_ function and executed;
 it then normally starts to submit the payment request, sending all credit card data to the given
 PSP.
 
 While processing the payment, PSPs usually need to communicate with the shop framework, in order to
 inform us about success or failure of the payment. To communicate with us, they may need a few
-endpoints. Each Payment provider may override the method ``get_urls()`` returning a list of
-urlpatterns, which then is used by the Django URL resolving engine.
+endpoints. Each class inheriting from :class:`shop.shop.payment.providers.PaymentProvider` may
+override the method ``get_urls()`` returning a list of urlpatterns, which then is used by the
+Django URL resolving engine.
 
 .. code-block:: python
 
+	from shop.payment.providers import PaymentProvider
+
 	class MyPSP(PaymentProvider):
 	    namespace = 'my-psp-payment'
 

docs/reference/search.rst

@@ -34,12 +34,14 @@ Configuration
 
 Download and install the latest version of the Elasticsearch binary. During development, all tests
 have been performed with version 7.5. After unzipping the file, start Elasticsearch in daemon mode
-by invoking :samp:`./path/to/elasticsearch-{version}/bin/elasticsearch -d`.
+by invoking:
+
+:samp:`./path/to/elasticsearch-{version}/bin/elasticsearch -d`.
 
 Check if the server answers on HTTP requests. Pointing a browser on
 `http://localhost:9200/ <http://localhost:9200/>`_ should return something similar to this:
 
-.. code-block::
+.. code-block:: bash
 
 	$ curl http://localhost:9200/
 	{
@@ -57,7 +59,7 @@ Install ``elasticsearch-dsl`` and ``django-elasticsearch-dsl`` using
 
     pipenv install django-elasticsearch-dsl
 
-In ``settings.py``, check that ``'django_elasticsearch_dsl'`` has been added to ``INSTALLED_APPS``.
+In ``settings.py``, add ``'django_elasticsearch_dsl'`` to the list of ``INSTALLED_APPS``.
 Configure the connection to the Elasticsearch database:
 
 .. code-block:: python