[docs] docs corrections

CONTRIBUTING.rst

@@ -100,15 +100,19 @@ Before you submit a pull request, check that it meets these guidelines:
 1. The pull request should include tests.
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
+   feature to the list in *README.rst*.
 3. Check https://travis-ci.org/scrapinghub/dateparser/pull_requests
    and make sure that the tests pass for all supported Python versions.
 4. Follow the core developers' advice which aim to ensure code's consistency regardless of variety of approaches used by many contributors.
 5. In case you are unable to continue working on a PR, please leave a short comment to notify us. We will be pleased to make any changes required to get it done.
 
 Guidelines for Adding New Languages
 -----------------------------------
-The language data required for parsing dates is contained in data/languages.yml file. 
+English is the primary language of the dateparser. Dates in all other languages are translated into English equivalents before they are parsed.
+The language data required for parsing dates is contained in *data/languages.yml* file. It contains variable parts that can be used in dates, language by language: month and week names - and their abbreviations, prepositions, conjunctions and frequently used descriptive words and phrases (like "today").
+The chosen data format is YAML because it is readable and simple to edit.
+Language data is extracted per language from YAML with :class:`LanguageDataLoader` and validated before being put into :class:`Language` class.
+
 Refer to :ref:`language-data-template` for details about its structure and take a look at already implemented languages for examples.
 As we deal with the delicate fabric of interwoven languages, tests are essential to keep the functionality across them.
 Therefore any addition or change should be reflected in tests.

README.rst

@@ -31,7 +31,7 @@ Features
 * Generic parsing of dates in English, Spanish, Dutch, Russian and several other languages and formats.
 * Generic parsing of relative dates like: ``'1 min ago'``, ``'2 weeks ago'``, ``'3 months, 1 week and 1 day ago'``.
 * Generic parsing of dates with time zones abbreviations or UTC offsets like: ``'August 14, 2015 EST'``, ``'July 4, 2013 PST'``, ``'21 July 2013 10:15 pm +0500'``.
-* Support for non-Gregorian calendar systems with the first addition of Persian Jalali Calendar <https://en.wikipedia.org/wiki/Iranian_calendars#Zoroastrian_calendar>_..
+* Support for non-Gregorian calendar systems with the first addition of :class:`JalaliParser <dateparser.calendars.jalali.JalaliParser>`. See `Persian Jalali Calendar <https://en.wikipedia.org/wiki/Iranian_calendars#Zoroastrian_calendar>`_ for more information.
 * Extensive test coverage.
 
 
@@ -109,7 +109,7 @@ Also, it requires PyYAML_ for its language detection module to work. The module
 
 
 Supported languages
-===========
+===================
 
 * Arabic
 * Belarusian
@@ -132,3 +132,16 @@ Supported languages
 * Turkish
 * Ukrainian
 * Vietnamese
+
+Supported Calendars
+===================
+* Gregorian calendar
+
+* Persian Jalali calendar
+
+Example of Use for Jalali Calendar
+==================================
+
+	>>> from dateparser.calendars.jalali import JalaliParser
+	>>> JalaliParser(u'جمعه سی ام اسفند ۱۳۸۷').get_date()
+	datetime.datetime(2009, 3, 20, 0, 0)

docs/dateparser.calendars.rst

@@ -12,19 +12,10 @@ dateparser.calendars.jalali module
 	:members: JalaliParser
 	:show-inheritance:
 
-Example of Use
-~~~~~~~~~~~~~~
-.. code-block:: python
-
-	In [1]: from dateparser.calendars.jalali import JalaliParser
-	
-	In [2]: JalaliParser(u'جمعه سی ام اسفند ۱۳۸۷').get_date()
-	Out[2]: datetime.datetime(2009, 3, 20, 0, 0)
-
 
 Module contents
 ---------------
 .. automodule:: dateparser.calendars
 	:members:
 	:show-inheritance:
-
+

docs/template.rst

@@ -5,7 +5,7 @@ Language Data Template
 
 .. sourcecode:: none
 
-	two-letter language name (e.g. en):
+	two-letter language code as defined in ISO-639-1 (https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). e.g. for English - en:
 	    name: language name (e.g. English)
 	    no_word_spacing: False (set to True for languages that do not use spaces between words)