Replace basic asciidoc markup with Sphnix

doc/index.rst

@@ -5,7 +5,7 @@ django-hstore documentation
 Introduction
 ------------
 
-_django-hstore_ is a niche library which integrates the `hstore <http://www.postgresql.org/docs/9.1/interactive/hstore.html>`_
+**django-hstore** is a niche library which integrates the `hstore <http://www.postgresql.org/docs/9.1/interactive/hstore.html>`_
 extension of PostgreSQL into Django.
 
 HStore brings the power of NoSQL key/value stores into PostgreSQL, giving us the
@@ -26,7 +26,7 @@ Features
 Django Admin widget
 ~~~~~~~~~~~~~~~~~~~
 
-django-hstore ships a nice admin widget that makes the field more user-friendly.
+**django-hstore** ships a nice admin widget that makes the field more user-friendly.
 
 .. image:: images/deafult-admin-widget.png
     :width: 650
@@ -62,15 +62,15 @@ Limitations
 
 - PostgreSQL's implementation of hstore has no concept of type; it stores a
   mapping of string keys to string values. Values are stored as strings in the
-  database regarding of their original type. *This limitation can be overcome by
+  database regarding of their original type. **This limitation can be overcome by
   using either the schema mode since version 1.3.0 or by using
-  the serialized dictionary field since version 1.3.6 of django_hstore*.
+  the serialized dictionary field since version 1.3.6 of django_hstore**.
 - The hstore extension is not automatically installed on use with this package: you must install it manually.
 - To run tests, hstore extension must be installed on template1 database.
-  To install hstore on template1: `$ psql -d template1 -c 'create extension hstore;'`
-- The admin widget will work with inlines only if using `StackedInline`. It won't work on `TabularInline`.
-- If `django.middleware.transaction.TransactionMiddleware` is enabled and the project is deployed
-  through `uwsgi`, the first request to a view working with models featuring hstore fields will raise an exception;
+  To install hstore on template1: ``$ psql -d template1 -c 'create extension hstore;'``
+- The admin widget will work with inlines only if using ``StackedInline``. It won't work on ``TabularInline``.
+- If ``django.middleware.transaction.TransactionMiddleware`` is enabled and the project is deployed
+  through ``uwsgi``, the first request to a view working with models featuring hstore fields will raise an exception;
   see `Django Ticket #22297 <https://code.djangoproject.com/ticket/22297>`_ for more details on this issue.
   This issue is specific to Django 1.6 and below.
 
@@ -80,9 +80,9 @@ Limitations
 
     To avoid this strange behavior you have two options:
 
-    - Install hstore on *template1* postgresql template database and recreate all databases/templates
+    - Install hstore on template1 postgresql template database and recreate all databases/templates
       from it, which allows all database to have the same oid for the hstore type (this is the recommended way).
-    - Disable global registering setting `DJANGO_HSTORE_ADAPTER_REGISTRATION` by setting it to `connection` in your settings. This
+    - Disable global registering setting ``DJANGO_HSTORE_ADAPTER_REGISTRATION`` by setting it to ``connection`` in your settings. This
       can have a performance impact because it registers the hstore extension for each new connection created
       (if you are using django 1.6, persistent connections - or any other connection pool - will help to
       reduce this impact).
@@ -91,26 +91,26 @@ Limitations
 Project Maturity
 ----------------
 
-_django-hstore_ is stable, widely used library with well defined deprecation policy.
+**django-hstore** is stable, widely used library with well defined deprecation policy.
 
 
 Deprecation policy
 ------------------
 
-At any momment of time, *django-hstore* developers will mantain support for three versions of django.
+At any momment of time, **django-hstore** developers will mantain support for three versions of django.
 
-As example: The current stable release of django is 1.9, so django-hstore supports the following django versions: 1.9, 1.8 and 1.7. When
+As example: The current stable release of django is 1.9, so **django-hstore** supports the following django versions: 1.9, 1.8 and 1.7. When
 django 1.10 is released, support for 1.7 will be dropped.
 
 User Guide
 ----------
 
-This section covers all aspectes that user want know about _django-hstore_.
+This section covers all aspectes that user want know about **django-hstore**.
 
 Install
 ~~~~~~~
 
-This section covers a installing _django-hstore_ and its requirements.
+This section covers a installing **django-hstore** and its requirements.
 
 Requirements
 ^^^^^^^^^^^^
@@ -143,7 +143,7 @@ Values are automatically converted to strings, fields constantly validate input
 
 If you are upgrading from an older version, ensure your application code works as expected.
 If it doesn't you will either have to update your code or tie your application's requirement
-to the older version of django-hstore (1.1.1).
+to the older version of **django-hstore** (1.1.1).
 
 
 Setup
@@ -152,7 +152,7 @@ Setup
 Basic setup
 ^^^^^^^^^^^
 
-First, add *django_hstore* to your `settings.INSTALLED_APPS`:
+First, add ``django_hstore`` to your ``settings.INSTALLED_APPS``:
 
 .. code-block:: python
 
@@ -171,9 +171,9 @@ Second, collect static files (needed for the admin widget) with:
 Multiple database setup
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-If for some reason you have to use django-hstore in a *multi-database setup* and
+If for some reason you have to use **django-hstore** in a *multi-database setup* and
 some of the database you are using don't have the hstore extension installed,
-you can skip hstore registration by setting `HAS_HSTORE` to `False` in your
+you can skip hstore registration by setting ``HAS_HSTORE`` to ``False`` in your
 database config:
 
 .. code-block:: python
@@ -198,16 +198,16 @@ database config:
         }
     }
 
-If you do that, then don't try to create `DictionaryField` in that database.
+If you do that, then don't try to create ``DictionaryField`` in that database.
 
 Be sure to check out `allow_syncdb <https://docs.djangoproject.com/en/1.5/topics/db/multi-db/#allow_syncdb>`_
 documentation.
 
 Available Settings
 ^^^^^^^^^^^^^^^^^^
 
-- `DJANGO_HSTORE_ADAPTER_REGISTRATION`: defaults to `global`; set this to `connection` if you need compatibility with SQLAlchemy
-- `DJANGO_HSTORE_ADAPTER_SIGNAL_WEAKREF`: the value of `weak` argument passed to the `connection_created` signal
+- ``DJANGO_HSTORE_ADAPTER_REGISTRATION``: defaults to ``global``; set this to ``connection`` if you need compatibility with SQLAlchemy
+- ``DJANGO_HSTORE_ADAPTER_SIGNAL_WEAKREF``: the value of ``weak`` argument passed to the ``connection_created`` signal
 
 Note to South users
 ^^^^^^^^^^^^^^^^^^^
@@ -224,28 +224,28 @@ Usage
 
 The library provides five principal classes:
 
-- `django_hstore.hstore.DictionaryField` +
+- ``django_hstore.hstore.DictionaryField`` +
   An ORM field which stores a mapping of string key/value pairs in a hstore
   column.
-- `django_hstore.hstore.SerializedDictionaryField` +
-  Similar to the `DictionaryField` with the exception that all submitted values
+- ``django_hstore.hstore.SerializedDictionaryField`` +
+  Similar to the ``DictionaryField`` with the exception that all submitted values
   in string key/value are encoded-to JSON upon writes to the database and decoded
   from JSON upon database reads. This allows for any JSON supported data type to
   be stored in an hstore column.
-- `django_hstore.hstore.ReferencesField` +
+- ``django_hstore.hstore.ReferencesField`` +
   An ORM field which builds on DictionaryField to store a mapping of string
   keys to django object references, much like ForeignKey.
-- `django_hstore.hstore.HStoreManager` +
+- ``django_hstore.hstore.HStoreManager`` +
   An ORM manager which provides much of the query functionality of the
   library.
-- `django_hstore.hstore.HStoreGeoManager` +
+- ``django_hstore.hstore.HStoreGeoManager`` +
   An additional ORM manager to provide Geodjango functionality as well.
 
 
 Model setup
 ^^^^^^^^^^^
 
-the `DictionaryField` definition is straightforward:
+the ``DictionaryField`` definition is straightforward:
 
 .. code-block:: python
 
@@ -260,11 +260,11 @@ the `DictionaryField` definition is straightforward:
         # IF YOU ARE USING POSTGIS:
         # objects = hstore.HStoreGeoManager()
 
-Since *django_hstore 1.3.0* it is possible to use the `DictionaryField` in *schema mode* in order to overcome the limit of values being only strings.
+Since **django_hstore 1.3.0** it is possible to use the ``DictionaryField`` in **schema mode** in order to overcome the limit of values being only strings.
 Another advantage of using the schema mode is that you can recycle the standard django fields in the admin and hopefully elsewhere.
-*This feature is available only from django 1.6 onwards*.
+**This feature is available only from django 1.6 onwards**.
 
-To use the schema mode you just need to supply a `schema` parameter to the `DictionaryField`:
+To use the schema mode you just need to supply a ``schema`` parameter to the ``DictionaryField``:
 
 .. code-block:: python
 
@@ -318,35 +318,35 @@ To use the schema mode you just need to supply a `schema` parameter to the `Dict
 
 After this declaration some additional virtual fields will be available in the model.
 Each virtual field will map to a key in the dictionary field, types are mantained behind the scenes
-by using the `to_python` method of the field class that has been specified for each key.
+by using the ``to_python`` method of the field class that has been specified for each key.
 
-The `schema` parameter is a list of dictionaries, each dictionary representing a field.
+The ``schema`` parameter is a list of dictionaries, each dictionary representing a field.
 
 Each dictionary should have the following keys:
 
-*name*: indicates the name of the attribute that will be created on the model
+**name**: indicates the name of the attribute that will be created on the model
 
-*class*: the field class that will be used to create the virtual field, you can pass it a string and it will look into django.db.models, alternatively you can pass it a concrete class derived from `django.db.models.Field` imported from anywhere
+**class**: the field class that will be used to create the virtual field, you can pass it a string and it will look into django.db.models, alternatively you can pass it a concrete class derived from ``django.db.models.Field`` imported from anywhere
 
-*kwargs*: the keyword arguments that will be passed to the Field class. Common arguments are `verbose_name`, `max_length`, `blank`, `choices`, `default`.
+**kwargs**: the keyword arguments that will be passed to the Field class. Common arguments are ``verbose_name``, ``max_length``, ``blank``, ``choices``, ``default``.
 
 The following standard django fields fields have been tested successfully:
 
- * `IntegerField`
- * `FloatField`
- * `DecimalField`
- * `BooleanField`
- * `CharField`
- * `TextField`
- * `DateField`
- * `DateTimeField`
- * `EmailField`
- * `GenericIPAddressField`
- * `URLField`
+ * ``IntegerField``
+ * ``FloatField``
+ * ``DecimalField``
+ * ``BooleanField``
+ * ``CharField``
+ * ``TextField``
+ * ``DateField``
+ * ``DateTimeField``
+ * ``EmailField``
+ * ``GenericIPAddressField``
+ * ``URLField``
 
-Other fields might work as well except for `FileField`, `ImageField`, and `BinaryField` which would need some additional work.
+Other fields might work as well except for ``FileField``, ``ImageField``, and ``BinaryField`` which would need some additional work.
 
-The schema of a DictionaryField can be changed at run-time if needed by using the `reload_schema` method (introduced in version 1.3.4):
+The schema of a DictionaryField can be changed at run-time if needed by using the ``reload_schema`` method (introduced in version 1.3.4):
 
 .. code-block:: python
 
@@ -361,7 +361,7 @@ The schema of a DictionaryField can be changed at run-time if needed by using th
     # turn off schema mode
     field.reload_schema(None)
 
-the `ReferenceField` definition is also straightforward:
+the ``ReferenceField`` definition is also straightforward:
 
 .. code-block:: python
 
@@ -371,7 +371,7 @@ the `ReferenceField` definition is also straightforward:
 
         objects = hstore.HStoreManager()
 
-the `SerializedDictionaryField` definition is very similar to the standard
+the ``SerializedDictionaryField`` definition is very similar to the standard
 dictionary field:
 
 .. code-block:: python
@@ -387,17 +387,17 @@ dictionary field:
         # IF YOU ARE USING POSTGIS:
         # objects = hstore.HStoreGeoManager()
 
-Optionally, the data accepts both a `serializer` and `deserializer` argument
-(which default to `json.dumps` and `json.loads`, respectively).  This allows
-allowing for customized manners of serialization. *Customizing the
+Optionally, the data accepts both a ``serializer`` and ``deserializer`` argument
+(which default to ``json.dumps`` and ``json.loads``, respectively).  This allows
+allowing for customized manners of serialization. **Customizing the
 serializer/deserializer is only partially implemented. It is NOT supported with
 the default Django admin widget (which attempts to serialize and deserialize all
-values with `json.dumps` and `json.loads`). Use at your own risk.*
+values with ``json.dumps`` and ``json.loads``). Use at your own risk.**
 
 Python API
 ~~~~~~~~~~
 
-You then treat the `data` field as simply a dictionary of string pairs:
+You then treat the ``data`` field as simply a dictionary of string pairs:
 
 .. code-block:: python
 
@@ -411,7 +411,7 @@ You then treat the `data` field as simply a dictionary of string pairs:
     empty.save()
     assert Something.objects.get(name='empty').data['a'] == '3'
 
-In *default mode*, Booleans, integers, floats, lists, and dictionaries will be converted to strings,
+In **default mode**, Booleans, integers, floats, lists, and dictionaries will be converted to strings,
 while lists, dictionaries, and booleans are converted into JSON formatted strings, so
 can be decoded if needed:
 
@@ -428,9 +428,9 @@ can be decoded if needed:
     json.loads(instance.data['dict']) == { 'list': ['a', False, 1] }
     # => True
 
-Since version *1.3.0* you can use the *schema mode* and you will be able to use
+Since version **1.3.0** you can use the **schema mode** and you will be able to use
 virtual fields derived from standard django fields which will take care of validation, default values, type casting, choices and so on.
-Each virtual field will be mapped to a key of the `DictionaryField`:
+Each virtual field will be mapped to a key of the ``DictionaryField``:
 
 .. code-block:: python
 
@@ -452,7 +452,7 @@ Each virtual field will be mapped to a key of the `DictionaryField`:
     >>> obj.data['float']
     9.99
 
-Since version *1.3.6* you can use the `SerializedDictionaryField` to store any
+Since version **1.3.6** you can use the ``SerializedDictionaryField`` to store any
 data type support in JSON. This has the specific advantage over the schema mode
 of not requiring the user to specify schema ahead of time.
 
@@ -558,16 +558,16 @@ You can also take advantage of some db-side functionality by using the manager:
     # remove a key/value pair from an hstore field
     >>> Something.objects.filter(name='something').hremove('data', 'b')
 
-    The hstore methods on manager pass all keyword arguments aside from `attr` and
-    `key` to `.filter()`.
+    The hstore methods on manager pass all keyword arguments aside from ``attr`` and
+    ``key`` to ``.filter()``.
 
 ReferenceField Usage
 ~~~~~~~~~~~~~~~~~~~~
 
-*ReferenceField* is a field that allows to reference other database objects
+**ReferenceField** is a field that allows to reference other database objects
 without using a classic ManyToMany relationship.
 
-Here's an example with the `ReferenceContainer` model defined in the *Model fields* section:
+Here's an example with the ``ReferenceContainer`` model defined in the **Model fields** section:
 
 .. code-block:: python
 
@@ -605,12 +605,12 @@ Once references have been retrieved they will be stored for any eventual subsequ
 Developers Guide
 ----------------
 
-This section covers everything that django-hstore developer / contributor want know.
+This section covers everything that **django-hstore** developer / contributor want know.
 
 Running tests
 ~~~~~~~~~~~~~
 
-Assuming one has the dependencies installed, and a *PostgreSQL 9.0+* server up and
+Assuming one has the dependencies installed, and a **PostgreSQL 9.0+** server up and
 running:
 
 .. code-block:: console
@@ -627,12 +627,12 @@ If you want to run the tests with psycopg2 backend you can do:
 
 You might need to tweak the DB settings according to your DB configuration.
 
-If you need to do so you can copy the file `local_settings.py.example` to `local_settings.py` and add
-your database tweaks on it. `local_settings.py` will be automatically imported in `settings.py`.
-The same applies for `local_settings_psycopg.py.example`, which will be imported in
-`local_settings_psycopg.py`.
+If you need to do so you can copy the file ``local_settings.py.example`` to ``local_settings.py`` and add
+your database tweaks on it. ``local_settings.py`` will be automatically imported in ``settings.py``.
+The same applies for ``local_settings_psycopg.py.example``, which will be imported in
+``local_settings_psycopg.py``.
 
-If after running this command you get an *error* saying:
+If after running this command you get an **error** saying:
 
 .. code-block:: console