Fix sphinx warnings (#35)

* chore(docs): clean-up conf.py

* fix(docs): note unproperly used

It also fixes this warning:

    Explicit markup ends without a blank line; unexpected unindent.

* fix(docs): remove invalid refs (deleted methods)

* fix(docs): intersphinx mapping

* fix(docs): ref to `datetime` redirects to `ULID.datetime` instead of `datetime.datetime` from the Python stdlib

---------

Co-authored-by: Martin Domke <mail@martindomke.net>

Author: BoboTiG

CHANGELOG.rst

@@ -9,7 +9,7 @@ Versions follow `Semantic Versioning <http://www.semver.org>`_
 ---------------------
 Changed
 ~~~~~~~
-* Raise `TypeError` instead of `ValueError` if constructor is called with value of wrong type.
+* Raise ``TypeError`` instead of ``ValueError`` if constructor is called with value of wrong type.
 * Update ``ruff`` linter rules and switch to ``hatch fmt``.
 
 Added
@@ -71,7 +71,7 @@ Added
 ~~~~~
 * Added a new flag ``--uuid4`` to the CLI ``show`` command, that converts the provided ``ULID``
   into an RFC 4122 compliant ``UUID``.
-* The `ulid build` command allows the use of the special value ``-`` for all options to read its
+* The ``ulid build`` command allows the use of the special value ``-`` for all options to read its
   inputs from ``stdin``. E.g.
 
   .. code-block:: bash
@@ -128,7 +128,7 @@ Changed
 Added
 ~~~~~
 * Added support for Python 3.10.
-* Added :attr:`__version__` variable to package.
+* Added ``__version__`` variable to package.
 
 
 `1.0.3`_ - 2021-07-14
@@ -153,7 +153,7 @@ Added
 Changed
 ~~~~~~~
 * Dropped support for Python 2. Only Python 3.6+ is supported.
-* The named constructor :meth:`.ULID.new` has been removed. Use one of the specifc named
+* The named constructor ``ULID.new`` has been removed. Use one of the specifc named
   constructors instead. For a new :class:`.ULID` created from the current timestamp use the
   standard constructor.
 
@@ -169,8 +169,8 @@ Changed
     ulid = ULID.from_timestamp(time.time())
     ulid = ULID.from_datetime(datetime.now())
 
-* The :meth:`.ULID.str` and :meth:`.ULID.int` methods have been removed in favour of the more
-  Pythonic special dunder-methods. Use `str(ulid)` and `int(ulid)` instead.
+* The ``ULID.str`` and ``ULID.int`` methods have been removed in favour of the more
+  Pythonic special dunder-methods. Use ``str(ulid)`` and ``int(ulid)`` instead.
 * Added the property :meth:`.ULID.hex` that returns a hex representation of the :class:`.ULID`.
 
   .. code-block:: python

docs/source/conf.py

@@ -12,7 +12,7 @@
 copyright = f"{datetime.now(timezone.utc).year}, Martin Domke"
 author = "Martin Domke"
 master_doc = "index"
-source_suffix = [".rst", ".md"]
+source_suffix = {".rst": "restructuredtext", ".md": "restructuredtext"}
 
 # The full version, including alpha/beta/rc tags
 release = ulid.__version__
@@ -23,6 +23,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
@@ -31,11 +32,6 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
-
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -76,7 +72,10 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
 pygments_style = "sphinx"
 
 autodoc_member_order = "groupwise"
+# ----------------------------------------------
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

ulid/__init__.py

@@ -1,11 +1,10 @@
 from __future__ import annotations
 
+import datetime
 import functools
 import os
 import time
 import uuid
-from datetime import datetime
-from datetime import timezone
 from typing import Any
 from typing import cast
 from typing import Generic
@@ -87,8 +86,8 @@ def __init__(self, value: bytes | None = None) -> None:
         )
 
     @classmethod
-    @validate_type(datetime)
-    def from_datetime(cls, value: datetime) -> Self:
+    @validate_type(datetime.datetime)
+    def from_datetime(cls, value: datetime.datetime) -> Self:
         """Create a new :class:`ULID`-object from a :class:`datetime`. The timestamp part of the
         `ULID` will be set to the corresponding timestamp of the datetime.
 
@@ -161,8 +160,9 @@ def from_int(cls, value: int) -> Self:
     def parse(cls, value: Any) -> Self:
         """Create a new :class:`ULID`-object from a given value.
 
-        .. note:: This method should only be used when the caller is trying to parse a ULID from
-        a value when they're unsure what format/primitive type it will be given in.
+        .. note::
+            This method should only be used when the caller is trying to parse a ULID from
+            a value when they're unsure what format/primitive type it will be given in.
         """
         if isinstance(value, ULID):
             return cast(Self, value)
@@ -183,7 +183,7 @@ def parse(cls, value: Any) -> Self:
             return cls.from_timestamp(value)
         if isinstance(value, float):
             return cls.from_timestamp(value)
-        if isinstance(value, datetime):
+        if isinstance(value, datetime.datetime):
             return cls.from_datetime(value)
         if isinstance(value, bytes):
             return cls.from_bytes(value)
@@ -211,16 +211,17 @@ def timestamp(self) -> float:
         """
         return self.milliseconds / constants.MILLISECS_IN_SECS
 
+
     @functools.cached_property
-    def datetime(self) -> datetime:
+    def datetime(self) -> datetime.datetime:
         """Return the timestamp part as timezone-aware :class:`datetime` in UTC.
 
         Examples:
 
             >>> ulid.datetime
             datetime.datetime(2020, 4, 30, 14, 33, 27, 560000, tzinfo=datetime.timezone.utc)
         """
-        return datetime.fromtimestamp(self.timestamp, timezone.utc)
+        return datetime.datetime.fromtimestamp(self.timestamp, datetime.timezone.utc)
 
     @functools.cached_property
     def hex(self) -> str: