[flake8-datetimez] Clarify docs for several rules (#20778)

## Summary

Resolves #19384.

- Distinguishes more clearly between `date` and `datetime` objects.
- Uniformly links to the relevant Python docs from rules in this
category.

I've tried to be clearer, but there's still a contradiction in the rules
as written: we say "use timezone-aware objects", but `date`s are
inherently timezone-naive.

Also, the full docs don't always match the error message: for instance,
in [DTZ012](https://docs.astral.sh/ruff/rules/call-date-fromtimestamp/),
the example says to use:
```python
datetime.datetime.fromtimestamp(946684800, tz=datetime.UTC)
```
while `fix_title` returns "Use `datetime.datetime.fromtimestamp(ts,
tz=...)**.date()**` instead".
I have left this as it was for now.

## Test Plan
Ran `mkdocs` locally and inspected result.

crates/ruff_linter/src/rules/flake8_datetimez/rules/call_date_fromtimestamp.rs

@@ -11,15 +11,15 @@ use crate::checkers::ast::Checker;
 /// Checks for usage of `datetime.date.fromtimestamp()`.
 ///
 /// ## Why is this bad?
-/// Python datetime objects can be naive or timezone-aware. While an aware
+/// Python date objects are naive, that is, not timezone-aware. While an aware
 /// object represents a specific moment in time, a naive object does not
 /// contain enough information to unambiguously locate itself relative to other
 /// datetime objects. Since this can lead to errors, it is recommended to
 /// always use timezone-aware objects.
 ///
-/// `datetime.date.fromtimestamp(ts)` returns a naive datetime object.
-/// Instead, use `datetime.datetime.fromtimestamp(ts, tz=...)` to create a
-/// timezone-aware object.
+/// `datetime.date.fromtimestamp(ts)` returns a naive date object.
+/// Instead, use `datetime.datetime.fromtimestamp(ts, tz=...).date()` to
+/// create a timezone-aware datetime object and retrieve its date component.
 ///
 /// ## Example
 /// ```python
@@ -32,14 +32,14 @@ use crate::checkers::ast::Checker;
 /// ```python
 /// import datetime
 ///
-/// datetime.datetime.fromtimestamp(946684800, tz=datetime.timezone.utc)
+/// datetime.datetime.fromtimestamp(946684800, tz=datetime.timezone.utc).date()
 /// ```
 ///
 /// Or, for Python 3.11 and later:
 /// ```python
 /// import datetime
 ///
-/// datetime.datetime.fromtimestamp(946684800, tz=datetime.UTC)
+/// datetime.datetime.fromtimestamp(946684800, tz=datetime.UTC).date()
 /// ```
 ///
 /// ## References

crates/ruff_linter/src/rules/flake8_datetimez/rules/call_date_today.rs

@@ -11,14 +11,15 @@ use crate::checkers::ast::Checker;
 /// Checks for usage of `datetime.date.today()`.
 ///
 /// ## Why is this bad?
-/// Python datetime objects can be naive or timezone-aware. While an aware
+/// Python date objects are naive, that is, not timezone-aware. While an aware
 /// object represents a specific moment in time, a naive object does not
 /// contain enough information to unambiguously locate itself relative to other
 /// datetime objects. Since this can lead to errors, it is recommended to
 /// always use timezone-aware objects.
 ///
-/// `datetime.date.today` returns a naive datetime object. Instead, use
-/// `datetime.datetime.now(tz=...).date()` to create a timezone-aware object.
+/// `datetime.date.today` returns a naive date object without taking timezones
+/// into account. Instead, use `datetime.datetime.now(tz=...).date()` to
+/// create a timezone-aware object and retrieve its date component.
 ///
 /// ## Example
 /// ```python

crates/ruff_linter/src/rules/flake8_datetimez/rules/call_datetime_today.rs

@@ -42,6 +42,9 @@ use crate::rules::flake8_datetimez::helpers;
 ///
 /// datetime.datetime.now(tz=datetime.UTC)
 /// ```
+///
+/// ## References
+/// - [Python documentation: Aware and Naive Objects](https://docs.python.org/3/library/datetime.html#aware-and-naive-objects)
 #[derive(ViolationMetadata)]
 pub(crate) struct CallDatetimeToday;
 

crates/ruff_linter/src/rules/flake8_datetimez/rules/call_datetime_without_tzinfo.rs

@@ -41,6 +41,9 @@ use crate::rules::flake8_datetimez::helpers::{self, DatetimeModuleAntipattern};
 ///
 /// datetime.datetime(2000, 1, 1, 0, 0, 0, tzinfo=datetime.UTC)
 /// ```
+///
+/// ## References
+/// - [Python documentation: Aware and Naive Objects](https://docs.python.org/3/library/datetime.html#aware-and-naive-objects)
 #[derive(ViolationMetadata)]
 pub(crate) struct CallDatetimeWithoutTzinfo(DatetimeModuleAntipattern);
 

crates/ruff_linter/src/rules/flake8_datetimez/rules/datetime_min_max.rs

@@ -38,6 +38,9 @@ use crate::checkers::ast::Checker;
 ///
 /// datetime.datetime.max.replace(tzinfo=datetime.UTC)
 /// ```
+///
+/// ## References
+/// - [Python documentation: Aware and Naive Objects](https://docs.python.org/3/library/datetime.html#aware-and-naive-objects)
 #[derive(ViolationMetadata)]
 pub(crate) struct DatetimeMinMax {
     min_max: MinMax,