docs: Update docs, add new examples

Author: Rodrigo Roldán

docs/source/changelog.md

@@ -2,6 +2,27 @@
 
 All versions are documented in this file.
 
+## [1.2.0] - 2025-06-25
+- Added locale-aware `diff_for_humans` via the new `humanize` module.
+- Introduced `eones/locales/` package for language messages.
+- Exposed `diff_for_humans` on `Date` and `Eones` classes.
+- Documented language extensibility and added tests.
+- Added comparison helpers `Date.is_same_day`, `Date.is_before`, `Date.is_after` and `Date.days_until`
+- Added `Date.as_local` property and renamed timezone conversion method to `as_zone`
+- Integration tests now skip if Django or SQLAlchemy are not installed
+
+---
+
+## [1.1.0] - 2025-06-13
+- Updated `pyproject.toml` to `1.1.0`.
+- Updated `README.md` to `1.1.0`.
+- Added Docstrings to all methods and classes in the source code and tests.
+- Added tests for all methods and classes.
+- Reached `99%` coverage for tests.
+- Added methods for handling ranges and periods.
+- Fixed bugs in comparison methods.
+- Added bugs for later fixes.
+
 ---
 
 ## [1.0.0] - 2025-05-19

docs/source/conf.py

@@ -18,13 +18,11 @@
 exclude_patterns = []
 
 html_baseurl = "https://roldriel.github.io/eones/"
-html_extra_path = ["extra"]
 html_theme = "alabaster"
 html_static_path = ["_static"]
 autodoc_mock_imports = ["django", "sqlalchemy"]
 html_theme_options = {
     "canonical_url": "https://roldriel.github.io/eones/",
-    "navigation_depth": 4,
 }
 html_context = {
     "display_github": True,

docs/source/eones.core.rst

@@ -25,6 +25,22 @@ eones.core.delta module
    :show-inheritance:
    :undoc-members:
 
+eones.core.delta\_calendar module
+---------------------------------
+
+.. automodule:: eones.core.delta_calendar
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+eones.core.delta\_duration module
+---------------------------------
+
+.. automodule:: eones.core.delta_duration
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 eones.core.parser module
 ------------------------
 

docs/source/eones.locales.rst

@@ -0,0 +1,26 @@
+eones.locales package
+=====================
+
+.. automodule:: eones.locales
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Submodules
+----------
+
+eones.locales.en module
+-----------------------
+
+.. automodule:: eones.locales.en
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+eones.locales.es module
+-----------------------
+
+.. automodule:: eones.locales.es
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/source/eones.rst

@@ -14,6 +14,7 @@ Subpackages
 
    eones.core
    eones.integrations
+   eones.locales
 
 Submodules
 ----------
@@ -42,6 +43,14 @@ eones.formats module
    :show-inheritance:
    :undoc-members:
 
+eones.humanize module
+---------------------
+
+.. automodule:: eones.humanize
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 eones.interface module
 ----------------------
 

docs/source/examples/advanced_usage.md

@@ -0,0 +1,163 @@
+# Advanced Usage of Eones
+
+This file contains advanced examples of date and time manipulation with Eones.
+
+## Advanced Date Manipulation
+
+### Truncation and Rounding
+
+```python
+date = Eones("2024-06-15 14:30:45")
+
+# Truncate to the start of different units
+date.floor("day")     # 2024-06-15 00:00:00
+date.floor("month")   # 2024-06-01 00:00:00
+date.floor("year")    # 2024-01-01 00:00:00
+date.floor("hour")    # 2024-06-15 14:00:00
+
+# Advance to the end of different units
+date.ceil("day")      # 2024-06-15 23:59:59
+date.ceil("month")    # 2024-06-30 23:59:59
+date.ceil("year")     # 2024-12-31 23:59:59
+
+# Round to the nearest unit
+date.round("hour")    # Round to the nearest hour
+date.round("day")     # Round to the nearest day
+```
+
+### Start and End of Periods
+
+```python
+date = Eones("2024-06-15 14:30:45")
+
+# Go to the start of different periods
+date.start_of("day")     # 2024-06-15 00:00:00
+date.start_of("week")    # Monday of that week
+date.start_of("month")   # 2024-06-01 00:00:00
+date.start_of("year")    # 2024-01-01 00:00:00
+
+# Go to the end of different periods
+date.end_of("day")       # 2024-06-15 23:59:59
+date.end_of("week")      # Sunday of that week
+date.end_of("month")     # 2024-06-30 23:59:59
+date.end_of("year")      # 2024-12-31 23:59:59
+```
+
+### Component Replacement
+
+```python
+date = Eones("2024-06-15 14:30:45")
+
+# Change specific components
+date.replace(day=1)           # Change to day 1 of the month
+date.replace(month=12)        # Change to December
+date.replace(year=2025)       # Change to 2025
+date.replace(hour=0, minute=0, second=0)  # Midnight
+
+print(date.format("%Y-%m-%d %H:%M:%S"))
+```
+
+## Comparisons and Validations
+
+### Date Comparisons
+
+```python
+date1 = Eones("2024-01-01")
+date2 = Eones("2024-12-31")
+date3 = Eones("2024-06-15")
+
+# Check if a date is between two others
+is_between = date3.is_between(date1, date2)
+print(is_between)  # True
+
+# Check if they are in the same week
+same_week = date1.is_same_week(date2)
+print(same_week)  # False
+
+# Check if they are in the same month/year
+same_month = date1.is_within(date3, check_month=True)
+same_year = date1.is_within(date3, check_month=False)
+```
+
+### Next Weekdays
+
+```python
+date = Eones("2024-06-15")  # Assume it's Saturday
+
+# Find the next Monday (0=Monday, 6=Sunday)
+next_monday = date.next_weekday(0)
+print(next_monday.format("%Y-%m-%d"))  # Date of next Monday
+
+# Next Friday
+next_friday = date.next_weekday(4)
+print(next_friday.format("%Y-%m-%d"))
+```
+
+## Date Ranges
+
+### Get period ranges
+
+```python
+date = Eones("2024-06-15")
+
+# Get ranges for different periods
+day_range = date.range("day")      # (day_start, day_end)
+month_range = date.range("month")    # (month_start, month_end)
+year_range = date.range("year")     # (year_start, year_end)
+
+# Ranges return datetime tuples
+start, end = month_range
+print(f"Month: from {start} to {end}")
+```
+
+## Additional Methods of the Date Class
+
+### Navigation by Weekdays
+
+```python
+date = Eones("2024-06-15")  # Assume it's Saturday
+
+# Find the next specific weekday
+next_monday = date.next_weekday(0)    # 0=Monday, 1=Tuesday, ..., 6=Sunday
+next_friday = date.next_weekday(4)
+
+# Find the previous specific weekday
+previous_wednesday = date.previous_weekday(2)
+
+print(next_monday.format("%Y-%m-%d"))     # Date of next Monday
+print(previous_wednesday.format("%Y-%m-%d")) # Date of previous Wednesday
+```
+
+### Dictionary Conversion
+
+```python
+date = Eones("2024-06-15 14:30:45")
+
+# Convert to dictionary with all components
+date_dict = date.to_dict()
+print(date_dict)
+# {
+#     'year': 2024,
+#     'month': 6,
+#     'day': 15,
+#     'hour': 14,
+#     'minute': 30,
+#     'second': 45,
+#     'microsecond': 0,
+#     'timezone': 'UTC'
+# }
+```
+
+### Specific Period Ranges
+
+```python
+date = Eones("2024-06-15")
+
+# Get specific ranges using the Range class
+quarter_range = date.quarter_range()  # Start and end of current quarter
+iso_week_range = date.week_range()    # ISO week (Monday to Sunday)
+
+# Ranges return datetime tuples
+quarter_start, quarter_end = quarter_range
+print(f"Quarter: {quarter_start} - {quarter_end}")
+```

docs/source/examples/basic_usage.md

@@ -0,0 +1,114 @@
+# Basic Usage of Eones
+
+This file contains basic examples to get started with the Eones library.
+
+## Import
+
+```python
+from eones import Eones
+```
+
+## Creating Dates
+
+### Different ways to create dates
+
+```python
+# Current date
+current_date = Eones()
+
+# From string (multiple formats supported)
+date1 = Eones("2024-12-25")
+date2 = Eones("25/12/2024")
+date3 = Eones("25-12-2024")
+date4 = Eones("2024-12-25 15:30:00")
+
+# From dictionary
+date5 = Eones({"year": 2024, "month": 12, "day": 25, "hour": 15})
+
+# From Python datetime
+from datetime import datetime
+date6 = Eones(datetime.now())
+
+# With specific timezone
+madrid_date = Eones("2024-12-25", tz="Europe/Madrid")
+mexico_date = Eones("2024-12-25", tz="America/Mexico_City")
+```
+
+## Date Formatting
+
+### Different output formats
+
+```python
+date = Eones("2024-12-25 15:30:00")
+
+# Different output formats
+print(date.format("%Y-%m-%d"))           # 2024-12-25
+print(date.format("%d/%m/%Y"))           # 25/12/2024
+print(date.format("%d de %B de %Y"))     # 25 de December de 2024
+print(date.format("%H:%M:%S"))           # 15:30:00
+```
+
+## Adding and Subtracting Time
+
+### Adding time to a date
+
+```python
+date = Eones("2024-01-15")
+
+# Add time
+date.add(days=10)          # Add 10 days
+date.add(months=2)         # Add 2 months
+date.add(years=1, days=5)  # Add 1 year and 5 days
+date.add(hours=3, minutes=30)  # Add 3 hours and 30 minutes
+
+print(date.format("%Y-%m-%d %H:%M"))  # Result after additions
+```
+
+## Differences Between Dates
+
+### Calculate differences
+
+```python
+date1 = Eones("2024-01-01")
+date2 = Eones("2024-12-31")
+
+# Calculate difference
+difference = date2.difference(date1)
+print(difference)  # Shows the difference in Delta format
+
+# Difference in specific units
+days_difference = date2.difference(date1, unit="days")
+months_difference = date2.difference(date1, unit="months")
+
+# Human-readable difference
+print(date2.diff_for_humans(date1))  # "11 months ago" (in English)
+print(date2.diff_for_humans(date1, locale="es"))  # "hace 11 meses" (in Spanish)
+```
+
+## Custom Parsing
+
+### Using custom formats
+
+```python
+# Use custom formats
+custom_formats = ["%d-%m-%Y", "%Y/%m/%d"]
+date = Eones("15-06-2024", formats=custom_formats)
+
+# Add additional formats to defaults
+date = Eones("15-06-2024", additional_formats=["%d-%m-%Y"])
+```
+
+## Localization
+
+### Support for multiple languages
+
+```python
+date1 = Eones("2024-01-01")
+date2 = Eones("2024-01-15")
+
+# In English (default)
+print(date2.diff_for_humans(date1))  # "2 weeks ago"
+
+# In Spanish
+print(date2.diff_for_humans(date1, locale="es"))  # "hace 2 semanas"
+```