Include calendar converters in sphinx docs and add basic usage to readme

README.md

@@ -140,7 +140,7 @@ An `UndateInterval` is a date range between two `Undate` objects. Intervals can
 ```
 
 You can initialize `Undate` or `UndateInterval` objects by parsing a date string with a specific converter, and you can also output an `Undate` object in those formats.
-Available converters are "ISO8601" and "EDTF" (but only)
+Currently available converters are "ISO8601" and "EDTF" and supported calendars.
 
 ```python
 >>> from undate import Undate
@@ -156,6 +156,33 @@ Available converters are "ISO8601" and "EDTF" (but only)
 <UndateInterval 1800/1900>
 ```
 
+### Calendars
+
+All `Undate` objects are calendar aware, and date converters include support for parsing and working with dates from other calendars. The Gregorian calendar is used by default; currently `undate` supports the Hijri Islamic calendar and the Anno Mundi Hebrew calendar based on calendar convertion logic implemented in the [convertdate](https://convertdate.readthedocs.io/en/latest/)package. 
+
+Dates are stored with the year, month, day and appropriate precision for the original calendar; internally, earliest and latest dates are calculated in Gregorian / Proleptic Gregorian calendar for standardized comparison across dates from different calendars.
+
+```python
+>>> from undate import Undate
+>>> tammuz4816 = Undate.parse("26 Tammuz 4816", "Hebrew")
+>>> tammuz4816
+<Undate '26 Tammuz 4816 Anno Mundi' 4816-04-26 (Hebrew)>
+>>> rajab495 = Undate.parse("Rajab 495", "Hijri")
+>>> rajab495
+<Undate 'Rajab 495 Hijrī' 0495-07 (Hijri)>
+>>> y2k = Undate.parse("2001", "EDTF")
+>>> y2k
+<Undate 2001 (Gregorian)>
+>>> [str(d.earliest) for d in [rajab495, tammuz4816, y2k]]
+['1102-04-28', '1056-07-17', '2001-01-01']
+>>> [str(d.precision) for d in [rajab495, tammuz4816, y2k]]
+['MONTH', 'DAY', 'YEAR']
+>>> sorted([rajab495, tammuz4816, y2k])
+[<Undate '26 Tammuz 4816 Anno Mundi' 4816-04-26 (Hebrew)>, <Undate 'Rajab 495 Hijrī' 0495-07 (Hijri)>, <Undate 2001 (Gregorian)>]
+```
+
+* * * 
+
 For more examples, refer to the [example notebooks](https://github.com/dh-tech/undate-python/tree/main/examples/notebooks/) included in this repository.
 
 ## Documentation

docs/undate/converters.rst

@@ -1,19 +1,25 @@
 Converters
 ==========
 
+Overview
+--------
+
 .. automodule:: undate.converters.base
    :members:
    :undoc-members:
 
+Formats
+--------
+
 ISO8601
--------
+^^^^^^^
 
 .. automodule:: undate.converters.iso8601
    :members:
    :undoc-members:
 
 Extended Date-Time Format (EDTF)
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. automodule:: undate.converters.edtf.converter
    :members:
@@ -23,8 +29,25 @@ Extended Date-Time Format (EDTF)
    :members:
    :undoc-members:
 
-.. transformer is more of an internal, probably doesn't make sense to include
-.. .. automodule:: undate.converters.edtf.transformer
-..    :members:
-..    :undoc-members:
+
+Calendars
+---------
+
+Gregorian
+^^^^^^^^^
+
+.. automodule:: undate.converters.calendars.gregorian
+   :members:
+
+Hijri (Islamic calendar)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: undate.converters.calendars.hijri.converter
+   :members:
+
+Anno Mundi (Hebrew calendar)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: undate.converters.calendars.hebrew.converter
+   :members: