Updated README.rst

README.rst

@@ -1,61 +1,65 @@
-==================================
+===================================
-PYNAMES — names generation library
+PYNAMES — Name Generation Library
-==================================
+===================================
 
-Pynames intended for generation of all sorts of names. Currently it implements generators for character names of different races and cultures:
+Pynames is a library designed for generating various types of names. It currently supports name generators for characters of different races and cultures, including:
 
-* Scandinavian: traditional names;
+* **Scandinavian**: traditional names
-* Russian: pagan names;
+* **Russian**: pagan names
-* Mongolian: traditional names;
+* **Mongolian**: traditional names
-* Korean: traditional names;
+* **Korean**: traditional names
-* Elven: DnD names;
+* **Elven**:
-* Elven: Warhammer names;
+   * DnD
-* Goblins: custom names;
+   * Warhamme
-* Orcs: custom names;
+* **Goblins**: custom names
-* Iron Kingdoms: caspian midlunder sulese;
+* **Orcs**: custom names
-* Iron Kingdoms: dwarf;
+* **Iron Kingdoms**:
-* Iron Kingdoms: gobber;
+   * Caspian, Midlunder, Sulese
-* Iron Kingdoms: iossan nyss;
+   * Dwarf
-* Iron Kingdoms: khadoran;
+   * Gobber
-* Iron Kingdoms: ogrun;
+   * Iossan, Nyss
-* Iron Kingdoms: ryn;
+   * Khadoran
-* Iron Kingdoms: thurian morridane;
+   * Ogrun
-* Iron Kingdoms: tordoran;
+   * Ryn
-* Iron Kingdoms: trollkin.
+   * Thurian, Morridane
+   * Tordoran
+   * Trollkin
 
-There are two supported languages : English & Russian. Russian language names are generated with forms for every case of a noun and time.
+The library supports two languages: **English** and **Russian**. For Russian, names are generated with forms for every grammatical case and tense.
 
-Currently implemented two generation algorithms:
+Two name generation algorithms are implemented:
 
-* ``pynames.from_list_generator`` — names are created from list of predefined words;
+* ``pynames.from_list_generator`` — names are created from a predefined list of words.
-* ``pynames.from_table_generator`` — names are created using templates, every part of template is gotten from separate table;
+* ``pynames.from_table_generator`` — names are created using templates, with each part of the template drawn from a separate table.
 
-The library is easily extensible. If you need extra functionality (including new languages), please, contact me, post an issue, or just make a pull request.
+The library is highly extensible. If you need additional functionality (including support for new languages), feel free to contact the author, post an issue, or submit a pull request.
 
 *************
 Installation
 *************
 
+Install the library via pip:
+
 ::
 
    pip install pynames
 
-*************
+********
 Usage
-*************
+********
 
 .. code:: python
 
    from pynames import GENDER, LANGUAGE
 
-All generators are divided by "races", so that all generators of elven names are placed in the module ``pynames.generators.elven``, etc.
+All generators are organized by "races," so, for instance, all elven name generators are in the module ``pynames.generators.elven``.
 
 .. code:: python
 
    from pynames.generators.elven import DnDNamesGenerator
    elven_generator = DnDNamesGenerator()
 
-Number of different names (male and female) and for each gender separately.
+You can retrieve the total number of unique names or the count for a specific gender:
 
 .. code:: python
 
@@ -68,7 +72,7 @@ Number of different names (male and female) and for each gender separately.
    In [6]: elven_generator.get_names_number(GENDER.FEMALE)
    Out[6]: 976474968
 
-Fast random name generation.
+Generate random names quickly:
 
 .. code:: python
 
@@ -78,13 +82,13 @@ Fast random name generation.
    In [8]: elven_generator.get_name_simple(GENDER.MALE)
    Out[8]: u'Caslithdar'
 
-   In [9]: elven_generator.get_name_simple(GENDER.MALE, LANGUAGE.EN) # English
+   In [9]: elven_generator.get_name_simple(GENDER.MALE, LANGUAGE.EN)  # English
    Out[9]: u'Mararon'
 
-   In [10]: print elven_generator.get_name_simple(GENDER.MALE, LANGUAGE.RU)  # Russian
+   In [10]: print(elven_generator.get_name_simple(GENDER.MALE, LANGUAGE.RU))  # Russian
    Ттомусиэл
 
-Instead of text, you can get the Name object with additional functionality.
+Instead of just text, you can retrieve a `Name` object with additional functionality:
 
 .. code:: python
 
@@ -106,7 +110,7 @@ Instead of text, you can get the Name object with additional functionality.
                    u"\u0430\u044d'\u0410\u043d\u0433\u0430\u0438\u0442\u0442\u043d\u0438\u0438\u043d\u0430\u043c\u0438",
                    u"\u0430\u044d'\u0410\u043d\u0433\u0430\u0438\u0442\u0442\u043d\u0438\u0438\u043d\u0430\u0445"]}}
 
-   In [13]: print u'\n'.join(name.get_forms_for(GENDER.MALE, language=LANGUAGE.RU))
+   In [13]: print(u'\n'.join(name.get_forms_for(GENDER.MALE, language=LANGUAGE.RU)))
    аэ'Ангаиттниин
    аэ'Ангаиттниина
    аэ'Ангаиттниину
@@ -121,4 +125,4 @@ Instead of text, you can get the Name object with additional functionality.
    аэ'Ангаиттниинах
 
    In [14]: name.genders
-   Out[14]: frozenset({u'm'}) # all genders
+   Out[14]: frozenset({u'm'})  # all genders